Protect-CmsMessage PowerShell Command

Protect-CmsMessage | Taking on PowerShell one cmdlet at a time | Weekly Blog

Share this post:

This is a part of an on-going blog series written by Adam Gordon. Each week, Adam will walk you through a PowerShell command, showing you when and how to use each one. This week, Adam covers Protect-CmsMessage.

When to use Protect-CmsMessage?

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.

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).

 Note: This cmdlet is only available on Windows.

What version of PowerShell am I using?

Get the PowerShell Version from your machine:

$PSVersionTable

This command shows you the PowerShell version information on your machine.

How to use Protect-CmsMessage?

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=adam@itpro.tv”
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 “C:\PShellTest\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.cer

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

Encrypt a message sent by email:

$Protected = “Hello World” | Protect-CmsMessage -To “*adam@itpro.tv*”

You encrypt a message, “Hello World”, by piping it to the Protect-CmsMessage cmdlet, and then save the encrypted message in a variable. The –To parameter uses the value of the Subject line in the certificate.

Learn last week’s command: Set-Acl.

Need PowerShell training? Check out ITProTV’s PowerShell online IT training courses.