PowerShell DSC Encryption

PowerShell’s Desired State Configuration allows for routines or classes to be run on remote machines by passing a text based “properties” object to the destination end-node. There are a growing number of Microsoft supplied “classes” and importantly, the framework allows for custom development of additional objects.

MOF Files define the inputs to the class that will be run remotely.

When DSC runs, it passes a plain text MOF file with values to a remote machine.

As the configuration file is plain text based, processes that require embedded credentials pose a major security risk. To mitigate the risk of password exposure, DSC provides an encryption mechanism to reduce the risk of passwords being divulged.

Digital Certificates

To encrypt MOF contents, we can use a digital certificate. A created certificate will hold two unique keys, one public and the other private. When two machines have copies of the same certificate, the sensitive data can be encrypted against the certificate with a Public key and unencrypted remotely by the second machine using the Private key.

For PowerShell’s DSC to utilise encryption, the first requirement is to generate a certificate. The important requirements is that the end node that receives the DSC MOF file is the machine that must unencrypt the file. To unencrypt it will be the remote machine that must hold the Private key… not the DSC serving machine.

There are a couple of ways that the end node can get a certificate (and hold the Private key). An auto-enrolment policy with a certificate server might be used. In this scenario, the DSC hosting server could get a copy of the issued certificate directly from the Certificate Authority.

In other situations, a self-signed certificate might be created on the end-node specifically for encrypting credential data being passed within DSC.

Certificate Requirements

Digital certificates can be used for many types of task.

The only requirement for PowerShell DSC encryption certificate is “key agreement”.

Vadims Podans’ PowerShell based self-signed certificate generator is universally used for the task

PowerShell DSC operates in the machine context so the command has to be run in a PowerShell session that’s opened in an Administrative context.

Certificate Stores

Self-Signed certificates aren’t trusted. To make the certificate usable, a copy will need to be inserted into a trusted Certificate Authority store as well.

Manually, this can be done by copy the Self-Signed certificate to the Trusted Root Certificate store.

Export the Certificate

The certificate must also be exported and copied to the DSC issuing server as it will utilise the file when encrypting DSC contents.

The Private key won’t be exported & DER encoding is fine.

Certificate Thumbprint

The DSC Issuing server will also need to know the thumbprint of the exported certificate.

There are a couple of traps with the certificate thumbprint and PowerShell DSC. Firstly, copy and pasting the thumbprint property from a certificate uses Unicode which adds a question mark to the start of the string which isn’t always visible (depending on your text editor). The other gotcha is that the thumbprint needs to be in uppercase if DSC is going to correctly use it for decoding.

Using PowerShell to create the certificate, trust the certificate, export the certificate and report the Thumbprint is the easiest way of ensuring that your certificate requirements are met for DSC Encryption.

Automating DSC Certificate Creation

The script below uses community contributed functions from Vadims Podans, James Kehr and Wayne Martin to create DSC encryption capable certificates on test-lab machines. Its purpose is to help in getting a working test environment for used with secured PowerShell DSC. As the script accesses the Local Machine Certificate Store, it must be run elevated.

Remember that the certificate must be created on the target end-node – not the server that will issue DSC objects.