PowerShell Logo Small

Protect-CmsMessage



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.

SYNOPSIS

Encrypts content by using the Cryptographic Message Syntax format.

SYNTAX


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

DESCRIPTION


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.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/?LinkId=394373
about_Providers
Get-CmsMessage
Unprotect-CmsMessage

REMARKS

<

Examples


Example 1: Create a certificate for encrypting content

PS C:\>[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%"

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.