Securing the MOF File

In this article

Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

DSC manages the configuration of server nodes
by applying information stored in a MOF file,
where the Local Configuration Manager (LCM) implements the desired end state.
Because this file contains the details of the configuration,
it’s important to keep it secure.
This topic describes how to ensure the target node has
encrypted the file.

Beginning with PowerShell version 5.0,
the entire MOF file is encrypted by default when it is applied to the node
using the Start-DSCConfiguration cmdlet.
The process described in this article is required only when implementing a solution
using the pull service protocol if certificates are not managed,
to ensure configurations downloaded by the target node can be decrypted and read by the system
before they are applied
(for example, the pull service available in Windows Server).
Nodes registered to Azure Automation DSC
will automatically have certificates installed and managed by the service
with no administrative overhead required.

Note:
This topic discusses certificates used for encryption.
For encryption, a self-signed certificate is sufficient,
because the private key is always kept secret and encryption does not imply trust of the document.
Self-signed certificates should not be used for authentication purposes.
You should use a certificate from a trusted Certification Authority (CA)
for any authentication purposes.

Prerequisites

To successfully encrypt the credentials used to secure a DSC configuration, make sure you have the following:

Each target node has an encryption-capable certificate saved its Personal Store. In Windows PowerShell, the path to the store is Cert:\LocalMachine\My. The examples in this topic use the
“workstation authentication” template, which you can find (along with other certificate templates) at Default Certificate Templates.

If you will be running this configuration on a computer other than the target node, export the public key of the certificate, and then import it to the computer you will run the
configuration from. Make sure that you export only the public key; keep the private key secure.

Overall process

Set up the certificates, keys, and thumbprints, making sure that each target node has copies of the certificate and the configuration computer has the public key and thumbprint.

Create a configuration data block that contains the path and thumbprint of the public key.

Create a configuration script that defines your desired configuration for the target node and sets up decryption on the target nodes by commanding the Local Configuration manager to decrypt the configuration data using the certificate and its thumbprint.

Run the configuration, which will set the Local Configuration Manager settings and start the DSC configuration.

Certificate Requirements

To enact credential encryption, a public key certificate must be available on the Target Node that is trusted by the computer being used to author the DSC configuration.
This public key certificate has specific requirements for it to be used for DSC credential encryption:

Key Usage:

Must contain: 'KeyEncipherment' and 'DataEncipherment'.

Should not contain: 'Digital Signature'.

Enhanced Key Usage:

Must contain: Document Encryption (1.3.6.1.4.1.311.80.1).

Should not contain: Client Authentication (1.3.6.1.5.5.7.3.2) and Server Authentication (1.3.6.1.5.5.7.3.1).

The Private Key for the certificate is available on the *Target Node_.

The Provider for the certificate must be "Microsoft RSA SChannel Cryptographic Provider".

Recommended Best Practice: Although you can use a certificate with containing a Key Usage of 'Digital Signature' or one of the Authentication EKU's, this will enable the encryption key
to be more easily misused and vulnerable to attack. So it is best practice to use a certificate created specifically for the purpose of securing DSC credentials that omits these Key Usage and
EKUs.

Any existing certificate on the Target Node that meets these criteria can be used to secure DSC credentials.

Certificate creation

There are two approaches you can take to create and use the required Encryption Certificate (public-private key pair).

Create it on the Target Node and export just the public key to the Authoring Node

Create it on the Authoring Node and export the entire key pair to the Target Node

Method 1 is recommended because the private key used to decrypt credentials in the MOF stays on the Target Node at all times.

Creating the Certificate on the Target Node

The private key must be kept secret, because is used to decrypt the MOF on the Target Node
The easiest way to do that is to create the private key certificate on the Target Node, and copy the public key certificate to the computer being used to author the DSC configuration into a MOF file.
The following example:

creates a certificate on the Target node

exports the public key certificate on the Target node.

imports the public key certificate into the my certificate store on the Authoring node.

Once exported, the DscPublicKey.cer would need to be copied to the Authoring Node.

Target Node: Windows Server 2012 R2/Windows 8.1 and earlier

Because the New-SelfSignedCertificate cmdlet on Windows Operating Systems prior to Windows 10 and Windows Server 2016 do not support the Type parameter, an alternate method of creating this certificate is required on these operating systems.
In this case you can use makecert.exe or certutil.exe to create the certificate.

On the Authoring Node: import the cert’s public key

Creating the Certificate on the Authoring Node

Alternately, the encryption certificate can be created on the Authoring Node, exported with the private key as a PFX file and then imported on the Target Node.
This is the current method for implementing DSC credential encryption on Nano Server.
Although the PFX is secured with a password it should be kept secure during transit.
The following example:

creates a certificate on the Authoring node.

exports the certificate including the private key on the Authoring node.

removes the private key from the Authoring node, but keeps the public key certificate in the my store.

imports the private key certificate into the root certificate store on the Target node.

it must be added to the root store so that it will be trusted by the Target node.

Once exported, the DscPrivateKey.pfx would need to be copied to the Target Node.

Target Node: Windows Server 2012 R2/Windows 8.1 and earlier

Because the New-SelfSignedCertificate cmdlet on Windows Operating Systems prior to Windows 10 and Windows Server 2016 do not support the Type parameter, an alternate method of creating this certificate is required on these operating systems.
In this case you can use makecert.exe or certutil.exe to create the certificate.

Configuration data

The configuration data block defines which target nodes to operate on, whether or not to encrypt the credentials, the means of encryption, and other information. For more information on the configuration data block, see Separating Configuration and Environment Data.

The elements that can be configured for each node that are related to credential encryption are:

NodeName - the name of the target node that the credential encryption is being configured for.

PsDscAllowPlainTextPassword - whether unencrypted credentials will be allowed to be passed to this node. This is not recommended.

Thumbprint - the thumbprint of the certificate that will be used to decrypt the credentials in the DSC Configuration on the Target Node. This certificate must exist in the Local Machine certificate store on the Target Node.

CertificateFile - the certificate file (containing the public key only) that should be used to encrypt the credentials for the Target Node. This must be either a DER encoded binary X.509 or Base-64 encoded X.509 format certificate file.

This example shows a configuration data block that specifies a target node to act on named targetNode, the path to the public key certificate file (named targetNode.cer), and the thumbprint for the public key.

$ConfigData= @{
AllNodes = @(
@{
# The name of the node we are describing
NodeName = "targetNode"
# The path to the .cer file containing the
# public key of the Encryption Certificate
# used to encrypt credentials for this node
CertificateFile = "C:\publicKeys\targetNode.cer"
# The thumbprint of the Encryption Certificate
# used to decrypt the credentials on target node
Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"
};
);
}

Configuration script

In the configuration script itself, use the PsCredential parameter to ensure that credentials are stored for the shortest possible time. When you run the supplied example, DSC will prompt you for credentials and then encrypt the MOF file using the CertificateFile that is associated with the target node in the configuration data block. This code example copies a file from a share that is secured to a user.

Setting up decryption

Before Start-DscConfiguration can work, you have to tell the Local Configuration Manager on each target node which certificate to use to decrypt the credentials, using the CertificateID resource to verify the certificate’s thumbprint. This example function will find the appropriate local certificate (you might have to customize it so it will find the exact certificate you want to use):

Running the configuration

At this point, you can run the configuration, which will output two files:

A *.meta.mof file that configures the Local Configuration Manager to decrypt the credentials using the certificate that is stored on the local machine store and identified by its thumbprint. Set-DscLocalConfigurationManager applies the *.meta.mof file.

A MOF file that actually applies the configuration. Start-DscConfiguration applies the configuration.

The feedback system for this content will be changing soon. Old comments will not be carried over. If content within a comment thread is important to you, please save a copy. For more information on the upcoming change, we invite you to read our blog post.