Today’s blog post is by guest author Mr. Ashley McGlone, also known as GoateePFE. Ashley is a Microsoft Premier Field Engineer who teaches and supports PowerShell for Microsoft Premier customers. You can find more content from Ashley at his blog on TechNet.

Certificates, Oh No!

One of the most common questions I get regarding PowerShell Desired State Configuration is about certificates. What kind do I need? How many? Where do they go? Most people enjoy working with certificates as much as they enjoy going to the dentist. Exactly. Many of us only touch the certificate server when we have no other choice. It is not a common skillset, and folks just know that if we mess up certificates it can be a very bad day. Now you start learning PowerShell DSC and realize that you need certificates. All that fear of certificates suddenly gets transposed to PowerShell DSC. In today’s blog post we will sort out certificate requirements for PowerShell DSC. This content is primarily aimed at those who need an overview of certificates related to PowerShell DSC. There is plenty of other PowerShell community content for those who want to dive deep after reading this.

Why certificates?

By its very nature PowerShell DSC handles sensitive infrastructure information. What hacker would not enjoy harvesting passwords from clear text files or clear text network conversations? Even more, what if they could intercept server configuration information over the wire to learn about potential attack vectors. For these reasons we need certificates to encrypt this sensitive data at rest and in transit.

Get to the point

The short answer is that there are two kinds of certificates you will likely need for PowerShell Desired State Configuration: 1. One for password encryption in the clear text MOF file at rest. 2. One for SSL encryption in transit, if you choose to follow the HTTPS pull server design. Certificates provide encryption in both cases.

Certificate #1: Password Encryption

For password protection you will need an encryption-capable certificate based on a template such as Workstation Authentication, Server Authentication, etc. If you are using Active Directory Certificate Services and Group Policy, then you can easily deploy and maintain these with autoenrollment. I recommend that customers create a global group to hold all of the Active Directory computer accounts of the servers that will need password encryption for DSC. Then grant this group Allow/AutoEnroll on the template on the certificate server. This same group can also be used to filter a certificate group policy to only DSC target servers. (In a domain environment this same global group of DSC computer accounts could also be used for IIS authentication for restricted access to the pull server.) Due to a limitation in the MOF file standard, the only resource property that we can encrypt is a credential, specifically the password portion of the credential. The user name will still be in clear text. Currently we do not have a solution for encrypting other sensitive information like database connection strings, for example. It is worth noting that not all configurations require credentials, eliminating the need for this certificate in those cases. Show me the MOF Here is what an unencrypted credential looks like in a MOF configuration file:

    instance of MSFT_Credential as $MSFT_Credential1ref
    {
    Password = "SuperSecretP@55word";
    UserName = "Contoso\\SuperUser";
    };

Here is what an encrypted credential looks like in a MOF configuration file:

    instance of MSFT_Credential as $MSFT_Credential1ref
    {
    Password = "IgOyIPdwzo53nLTj2TtZXkBgrGkon1gYWEtSD2GfExFobYzfQ4yzAxUMxwuTF8WUGGRkw
    wPSx5oW9MeOZZhKgXAL8DW9F+SvT8TEVf4FSAOstmLLpkv5T5m3lAjz75Xh7r0+pghgYjTgSdhY/sH1zt
    6nSiD4c76PFtsWB1TL3xvv/Uf5km0MO9JXl3tsMTWMA+A1zM7b0h/tVjaU3jiC/RpSwVIFDu7i7wxwBAc
    LxWmBsqeU8ZxVdnpBFG6ZbQypkDOzdrSBb4SyD3NFRvlLvg7DMRPu7vmZL65lfJ67E7xVi5GfXiZ+hxU8
    hBIxVgAmr1TvGZ4KhvRrSZNjTeNI9z==";
    UserName = "Contoso\\SuperUser";
    };

Password Encryption Circus Now how exactly does the password encryption work? How do I encrypt and decrypt the password? Great question. I’m glad you asked. On the server where you generate the MOF files (ie. the build server) you will need a copy of the certificate public key from each target node. Wait! What?! Yes, you heard that right. You need to export a copy of the certificate public key from each of the target nodes and store them on the build server. During MOF creation for a node you will point to a local copy of the public key from the target node. This public key encrypts the password. When the node receives the MOF file (via either push or pull) it will use its local private key to decrypt the password. This means that the build server will have a folder piled full of certificate public key files. Now understand that these are harmless from a security perspective. There is no danger if a public key is exposed. That’s why they call it a public key. An alternative to harvesting public keys from every single node is to export them directly from the Active Directory Certificate Server. This removes the dependency of connectivity to every node. See this blog post for one scripted approach. One catch to using a unique certificate per node is that you cannot share a single configuration across multiple nodes with a single MOF file. The MOF file will use a single public key for encryption, but each node has a unique private key for decryption. In this case you will need to generate a unique MOF file for each node. The configuration inside the MOF can be exactly the same, but the passwords will be uniquely encrypted per node. For more information on this topic, specific DSC syntax, and a helper function see the PowerShell team blog post Want to secure credentials in Windows PowerShell Desired State Configuration. Are you serious? The next question I usually get is, “Are you serious? Isn’t there an easier way?” Let me respond with another question, “Have you ever seen the words easy and security used in the same sentence?” I have some customers who have chosen to share a single certificate across multiple DSC nodes for password encryption, and their InfoSec team has approved the design. So how does this work? You can manually (or via script) install the same certificate across all nodes. Then you encrypt all MOF file password data with a single certificate public key. Easy right? Well yes and no. This presents two challenges:

1. When you install a private key certificate you must provide a password. In order to scale this realistically now I need to automate the installation of the shared private key certificate across all those nodes. But now how do I protect the private key password? There are an assortment of techniques, but this moves the security target to protecting the private key password.
2. Every machine has the same private key. If one gets compromised, then theoretically the hacker could decrypt information on all of the nodes sharing that certificate.

For these reasons the shared-certificate method is considered less secure. The bottom line on password encryption This is all really a matter of automating the MOF generation process. In an ideal world (domain-joined, AD Certificate Services, etc.) using unique certificates should have no impact on administrative effort. Once you have written your own tooling scripts to manage the certificate process this is no longer a factor. However, if you are managing certificates in a less-automated fashion (third party solutions, edge networks, etc.) you will want to make your design decisions carefully.

Certificate #2: HTTPS Pull Server

Now that we have the passwords encrypted at rest, what about encrypting the configuration data in transit? This one is much easier. If you are pushing configurations to nodes, then the network conversation is automatically encrypted over WinRM/WS-MAN. This is the same encryption used for PowerShell remoting on port 5985. Done deal. (It is possible to use SSL for WinRM, which would double-encrypt the network conversation. In this case the same SSL certificate used for an HTTPS pull server would work. The added benefit here would be mutual authentication.) If you are pulling configurations, then you want to use an HTTPS pull server. Neither an HTTP or file share pull server provide encryption in transit. Building a web server that uses HTTPS is a common IT task. With PowerShell DSC it is no different. Request a web SSL certificate, install it on the web server, and then bind it to the port for the site. This process is also entirely automation-friendly. You can programmatically request the certificate, install it, and then insert the certificate thumbprint into the configuration that builds the pull server. This can be a one-time event.

What about push vs. pull?

The MOF delivery mechanism is completely unrelated to the encryption of passwords inside the MOF. Passwords will be encrypted with Certificate #1 above. This has no bearing on a push vs. pull design. In this case the build server (which could also be the pull server or the server from which you push configurations) holds exported public keys. This certificate has nothing to do with push or pull. Certificate #2 comes into play for either an HTTPS pull server or the over-achiever who wants to double-encrypt WinRM over SSL for push.

Security in Azure DSC

So far this conversation has been about classic DSC, if you can call it classic already. In Azure the at rest and in transit encryption is handled more simply. In Azure when you use the DSC Extension we encrypt credentials automatically using the local Azure VM certificate. Also the configuration is transmitted over HTTPS automatically. See this PowerShell team blog post for more information.

So what does Microsoft recommend?

Assuming that you are using a pull model, then I recommend an HTTPS pull server and a unique encryption certificate per node. Use automation and tooling to alleviate the administrative burden of certificate management where possible. Notice this is what I recommend, and I am a Premier Field Engineer employee of Microsoft. Others may have different recommendations, but I believe this advice represents the best out-of-the-box guidance based on present PowerShell DSC capabilities. With well over a year of WMF 5.0 preview releases you know that we are committed to improving the PowerShell DSC experience. Continue to watch this area for future announcements around securing DSC configuration files.

Sorting Out Certificates

To help my customers I created the following two charts to explain the PowerShell DSC certificate design choices and the pros and cons of each. Feel free to post these on your cube wall or share them with others as a handy reference.

Where do I get more information?

Microsoft Premier Customers can register for one of our PowerShell DSC workshops either as an on-site experience, online instructor-led workshop, or online streaming video workshop. See this post for more information on the video option. In this workshop we explain and demonstrate the specifics of the certificate scenarios described above. Contact your Premier Technical Account Manager (TAM) for more information. For free training on encrypting credentials with certificates see the Microsoft Virtual Academy course Getting Started with PowerShell Desired State Configuration (DSC), module 6 Writing better configurations at the 03:40 minute mark.