PowerShell Logo Small


This is the built-in help made by Microsoft for the command 'Protect-CmsMessage', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.


Encrypts content by using the Cryptographic Message Syntax format.


Protect-CmsMessage [-To] <CmsMessageRecipient[]> [-Content] <PSObject> [[-OutFile] <String>] [<CommonParameters>]
Protect-CmsMessage [-To] <CmsMessageRecipient[]> [-LiteralPath] <String> [[-OutFile] <String>] [<CommonParameters>]
Protect-CmsMessage [-To] <CmsMessageRecipient[]> [-Path] <String> [[-OutFile] <String>] [<CommonParameters>]

Search powershellhelp.space


The Cryptographic Message Syntax 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 is not sensitive data. If any content is encrypted with this public key, only your private key can decrypt it. For more
information about Public Key Cryptography, see http://en.wikipedia.org/wiki/Public-key_cryptography.

Before you can run the Protect-CmsMessage cmdlet, you must have an encryption certificate set up. To be recognized in Windows PowerShell, encryption certificates require a
unique extended key usage (EKU) identifier to identify them as data encryption certificates (such as the identifiers for Code Signing and Encrypted Mail). For an example of
a certificate that would work for document encryption, see Example 1 in this topic.



Online Version: http://go.microsoft.com/fwlink/?LinkId=394373




Example 1: Create a certificate for encrypting content

PS C:\>[Version]
Signature = "$Windows NT$"


Subject = "cn=youralias@emailaddress.com"
MachineKeySet = false
KeyLength = 2048
HashAlgorithm = Sha1
Exportable = true
RequestType = Cert
ValidityPeriod = "Years"
ValidityPeriodUnits = "1000"


After you have created the certificate file, run the following command to add the certificate file to the certificate store.Now you are ready to encrypt and decrypt content.
PS C:\>certreq -new DocumentEncryption.inf DocumentEncryption.cer

Before you can run the Protect-CmsMessage cmdlet, you must have an encryption certificate set up. Change the text in the Subject line to your name, email, or other
identifier, and save the certificate in a file (such as DocumentEncryption.inf, as shown in this example).

Example 2: Encrypt a message sent by email

PS C:\>$protected = "Hello World" | Protect-CmsMessage -To "*youralias@emailaddress.com*"

In the following example, you encrypt a message, Hello World, by saving the message in a variable, and then piping it to the Protect-CmsMessage cmdlet. The To parameter is
using the value of the Subject line in the certificate.

Example 3: View document encryption certificates

PS C:\>58 [Cert:\currentuser\my]
>> Get-ChildItem -DocumentEncryptionCert

To view document encryption certificates in the certificate provider, you can add the DocumentEncryptionCert dynamic parameter of Get-ChildItem, available only when the
certificate provider is loaded.