chef 15.2.20 → 15.3.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebc000729c7b20f311492291cbab02cda4a447d907b06cd3ec1b04ca8f4de918
-  data.tar.gz: cbd1506bf54604980849f773afd9248232ce86a48ad9e248820af87aa29b3599
+  metadata.gz: 772f0452477ac76959f28ac0daa680847762bf0bf0e26e1277d76d9b40f143fd
+  data.tar.gz: 53a57e2a7d1988e49e1a60ab13be59cb5f3c4cabeb4a5e55126a117f84d60112
 SHA512:
-  metadata.gz: 737c2c9fdcc00c0d2c880aee3a0b992a137702b2e93fb3792e7781351b32c9bcbea04e7f4b8a194db56430d7ee734f67dba2e06be875ef98d3bde8c865e8e1e0
-  data.tar.gz: 8f77e8ab632390a699836231a559e7b6caea714b09e059a5fdab17d91c9addaef8a1c5971a88758b4c4ec3c9e89909dfec2df92ff202a3f9f619d13f67f9b28e
+  metadata.gz: 798400e33a9696516462fa405a1297b2284b21773cb9898ddf0245dc05a35a01dee33152a2b78dc7f36c4b0dd40a3c5102766675bce2eca03c50c6f3d7a3083a
+  data.tar.gz: 383c4ad9b5c05cbd43e58c249eaecf53b442cc2ce1b05cb1d8abfe6aaf624b20f9c707b21f18c3af00b6b8efba05ad8d9119ce01b724b2497b0a2897a65871f3

data/README.md

@@ -1,9 +1,8 @@
 # Chef Infra
 [![Code Climate](https://codeclimate.com/github/chef/chef.svg)](https://codeclimate.com/github/chef/chef)
 [![Build Status](https://badge.buildkite.com/c82093430ceec7d27af05febb9dcafe3aa331fff9d74c0ab9d.svg?branch=master)](https://buildkite.com/chef-oss/chef-chef-master-verify)
-[![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/chef?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/chef/branch/master)
 [![Gem Version](https://badge.fury.io/rb/chef.svg)](https://badge.fury.io/rb/chef)
-[![](https://img.shields.io/badge/Release%20Policy-Cadence%20Release-brightgreen.svg)](https://github.com/chef/chef-rfc/blob/master/rfc086-chef-oss-project-policies.md#cadence-release)
+[![](https://img.shields.io/badge/Release%20Policy-Cadence%20Release-brightgreen.svg)](https://github.com/chef/chef/blob/v15.2.21/docs/dev/design_documents/client_release_cadence.md)
 
 **Umbrella Project**: [Chef Infra](https://github.com/chef/chef-oss-practices/blob/master/projects/chef-infra.md)
 

data/chef.gemspec

@@ -16,13 +16,14 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= 2.5.0"
 
   s.add_dependency "chef-config", "= #{Chef::VERSION}"
-  s.add_dependency "train-core", "~> 2.0", ">= 2.0.12"
+  s.add_dependency "train-core", "~> 3.0"
+  s.add_dependency "train-winrm"
 
   s.add_dependency "license-acceptance", "~> 1.0", ">= 1.0.5"
   s.add_dependency "mixlib-cli", ">= 2.1.1", "< 3.0"
   s.add_dependency "mixlib-log", ">= 2.0.3", "< 4.0"
   s.add_dependency "mixlib-authentication", "~> 2.1"
-  s.add_dependency "mixlib-shellout", ">= 2.4", "< 4.0"
+  s.add_dependency "mixlib-shellout", ">= 3.0.3", "< 4.0"
   s.add_dependency "mixlib-archive", ">= 0.4", "< 2.0"
   s.add_dependency "ohai", "~> 15.0"
 

data/lib/chef/application.rb

@@ -163,7 +163,7 @@ class Chef
         chef_config[:specific_recipes] =
           cli_arguments.map { |file| File.expand_path(file) }
       else
-        Chef::Application.fatal!("Invalid arguments are not supported by the chef-client: \"" +
+        Chef::Application.fatal!("Invalid argument; could not find the following recipe files: \"" +
           cli_arguments.select { |file| !File.file?(file) }.join('", "') + '"')
       end
     end

data/lib/chef/application/base.rb

@@ -340,6 +340,13 @@ class Chef::Application::Base < Chef::Application
 
   private
 
+  def windows_interval_error_message
+    "Windows #{Chef::Dist::PRODUCT} interval runs are not supported in #{Chef::Dist::PRODUCT} 15 and later." +
+      "\nConfiguration settings:" +
+      ("\n  interval  = #{Chef::Config[:interval]} seconds" if Chef::Config[:interval]).to_s +
+      "\nPlease manage #{Chef::Dist::PRODUCT} as a scheduled task instead."
+  end
+
   def unforked_interval_error_message
     "Unforked #{Chef::Dist::PRODUCT} interval runs are disabled by default." +
       "\nConfiguration settings:" +

data/lib/chef/application/client.rb

@@ -128,8 +128,12 @@ class Chef::Application::Client < Chef::Application::Base
       Chef::Config[:client_fork] = !!Chef::Config[:interval]
     end
 
-    if !Chef::Config[:client_fork] && Chef::Config[:interval] && !Chef::Platform.windows?
-      Chef::Application.fatal!(unforked_interval_error_message)
+    if Chef::Config[:interval]
+      if Chef::Platform.windows?
+        Chef::Application.fatal!(windows_interval_error_message)
+      elsif !Chef::Config[:client_fork]
+        Chef::Application.fatal!(unforked_interval_error_message)
+      end
     end
 
     if Chef::Config[:json_attribs]

data/lib/chef/application/solo.rb

@@ -102,7 +102,13 @@ class Chef::Application::Solo < Chef::Application::Base
       Chef::Config[:client_fork] = !!Chef::Config[:interval]
     end
 
-    Chef::Application.fatal!(unforked_interval_error_message) if !Chef::Config[:client_fork] && Chef::Config[:interval]
+    if Chef::Config[:interval]
+      if Chef::Platform.windows?
+        Chef::Application.fatal!(windows_interval_error_message)
+      elsif !Chef::Config[:client_fork]
+        Chef::Application.fatal!(unforked_interval_error_message)
+      end
+    end
 
     if Chef::Config[:recipe_url]
       cookbooks_path = Array(Chef::Config[:cookbook_path]).detect { |e| Pathname.new(e).cleanpath.to_s =~ %r{/cookbooks/*$} }

data/lib/chef/cookbook/gem_installer.rb

@@ -66,8 +66,13 @@ class Chef
                 tf.close
                 Chef::Log.trace("generated Gemfile contents:")
                 Chef::Log.trace(IO.read(tf.path))
-                so = shell_out!("bundle install", cwd: dir, env: { "PATH" => path_with_prepended_ruby_bin })
-                Chef::Log.info(so.stdout)
+                # Skip installation only if Chef::Config[:skip_gem_metadata_installation] option is true
+                unless Chef::Config[:skip_gem_metadata_installation]
+                  # Add additional options to bundle install
+                  cmd = [ "bundle", "install", Chef::Config[:gem_installer_bundler_options] ]
+                  so = shell_out!(cmd, cwd: dir, env: { "PATH" => path_with_prepended_ruby_bin })
+                  Chef::Log.info(so.stdout)
+                end
               end
             end
             Gem.clear_paths

data/lib/chef/exceptions.rb

@@ -509,5 +509,17 @@ class Chef
         super "Conflicting requirements for gem '#{gem_name}': Both #{value1.inspect} and #{value2.inspect} given for option #{option.inspect}"
       end
     end
+
+    class UnifiedModeImmediateSubscriptionEarlierResource < RuntimeError
+      def initialize(notification)
+        super "immediate subscription from #{notification.resource} resource cannot be setup to #{notification.notifying_resource} resource, which has already fired while in unified mode"
+      end
+    end
+
+    class UnifiedModeBeforeSubscriptionEarlierResource < RuntimeError
+      def initialize(notification)
+        super "before subscription from #{notification.resource} resource cannot be setup to #{notification.notifying_resource} resource, which has already fired while in unified mode"
+      end
+    end
   end
 end

data/lib/chef/knife/bootstrap.rb

@@ -672,6 +672,14 @@ class Chef
       def do_connect(conn_options)
         @connection = TrainConnector.new(host_descriptor, connection_protocol, conn_options)
         connection.connect!
+      rescue Train::UserError => e
+        if !conn_options.key?(:pty) && e.reason == :sudo_no_tty
+          ui.warn("#{e.message} - trying with pty request")
+          conn_options[:pty] = true # ensure we can talk to systems with requiretty set true in sshd config
+          retry
+        else
+          raise
+        end
       end
 
       # Fail if both first_boot_attributes and first_boot_attributes_from_file
@@ -895,7 +903,6 @@ class Chef
         opts = {}
         return opts if winrm?
 
-        opts[:pty] = true # ensure we can talk to systems with requiretty set true in sshd config
         opts[:non_interactive] = true # Prevent password prompts from underlying net/ssh
         opts[:forward_agent] = (config_value(:ssh_forward_agent) === true)
         opts[:connection_timeout] = session_timeout

data/lib/chef/knife/bootstrap/templates/chef-full.erb

@@ -173,7 +173,7 @@ do_download() {
   <%= knife_config[:bootstrap_install_command] %>
 <% else %>
   install_sh="<%= knife_config[:bootstrap_url] ? knife_config[:bootstrap_url] : "https://omnitruck.chef.io/chef/install.sh" %>"
-  if test -f /usr/bin/<%= Chef::Dist::CLIENT %>}; then
+  if test -f /usr/bin/<%= Chef::Dist::CLIENT %>; then
     echo "-----> Existing <%= Chef::Dist::PRODUCT %> installation detected"
   else
     echo "-----> Installing Chef Omnibus (<%= @config[:channel] %>/<%= version_to_install %>)"

data/lib/chef/knife/bootstrap/train_connector.rb

@@ -123,13 +123,13 @@ class Chef
               # eg. /tmp/chef_XXXXXX.
               # Use mkdir to create TEMP dir to get rid of mktemp
               dir = "#{DEFAULT_REMOTE_TEMP}/chef_#{SecureRandom.alphanumeric(6)}"
-              cmd = "mkdir -p %s" % dir
+              run_command!("mkdir -p '#{dir}'")
               # Ensure that dir has the correct owner.  We are possibly
               # running with sudo right now - so this directory would be owned by root.
               # File upload is performed over SCP as the current logged-in user,
               # so we'll set ownership to ensure that works.
-              cmd += " && sudo chown #{config[:user]} '#{dir}'"
-              run_command!(cmd)
+              run_command!("chown #{config[:user]} '#{dir}'") if config[:sudo]
+
               dir
             end
           end

data/lib/chef/knife/cookbook_metadata_from_file.rb

@@ -28,7 +28,7 @@ class Chef
         require_relative "../cookbook/metadata"
       end
 
-      banner "knife cookbook metadata from FILE (options)"
+      banner "knife cookbook metadata from file FILE (options)"
 
       def run
         file = @name_args[0]

data/lib/chef/node.rb

@@ -87,8 +87,6 @@ class Chef
     # after the run_context has been set on the node, go through the cookbook_collection
     # and setup the node[:cookbooks] attribute so that it is published in the node object
     def set_cookbook_attribute
-      return unless run_context.cookbook_collection
-
       run_context.cookbook_collection.each do |cookbook_name, cookbook|
         automatic_attrs[:cookbooks][cookbook_name][:version] = cookbook.version
       end

data/lib/chef/policy_builder/expand_node_object.rb

@@ -75,7 +75,6 @@ class Chef
       #
       def setup_run_context(specific_recipes = nil, run_context = nil)
         run_context ||= Chef::RunContext.new
-
         run_context.events = events
         run_context.node = node
 
@@ -93,6 +92,7 @@ class Chef
 
         cookbook_collection.validate!
         cookbook_collection.install_gems(events)
+
         run_context.cookbook_collection = cookbook_collection
 
         # TODO: move this into the cookbook_compilation_start hook

data/lib/chef/policy_builder/policyfile.rb

@@ -177,16 +177,17 @@ class Chef
       #
       # @return [Chef::RunContext]
       def setup_run_context(specific_recipes = nil, run_context = nil)
+        run_context ||= Chef::RunContext.new
+        run_context.node = node
+        run_context.events = events
+
         Chef::Cookbook::FileVendor.fetch_from_remote(api_service)
         sync_cookbooks
         cookbook_collection = Chef::CookbookCollection.new(cookbooks_to_sync)
         cookbook_collection.validate!
         cookbook_collection.install_gems(events)
 
-        run_context ||= Chef::RunContext.new
-        run_context.node = node
         run_context.cookbook_collection = cookbook_collection
-        run_context.events = events
 
         setup_chef_class(run_context)
 

data/lib/chef/provider.rb

@@ -1,7 +1,7 @@
 #
 # Author:: Adam Jacob (<adam@chef.io>)
 # Author:: Christopher Walters (<cw@chef.io>)
-# Copyright:: Copyright 2008-2016, 2009-2018, Chef Software Inc.
+# Copyright:: Copyright 2008-2016, 2009-2019, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -238,8 +238,10 @@ class Chef
     def compile_and_converge_action(&block)
       old_run_context = run_context
       @run_context = run_context.create_child
+      @run_context.resource_collection.unified_mode = new_resource.class.unified_mode
+      runner = Chef::Runner.new(@run_context)
       return_value = instance_eval(&block)
-      Chef::Runner.new(run_context).converge
+      runner.converge
       return_value
     ensure
       if run_context.resource_collection.any?(&:updated?)

data/lib/chef/provider/ifconfig.rb

@@ -109,18 +109,20 @@ class Chef
           #       RX errors 0  dropped 0  overruns 0  frame 0
           #       TX packets 1244218  bytes 977339327 (932.0 MiB)
           #       TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
+          #
+          # Permalink for addr_regex : https://rubular.com/r/JrykUpfjRnYeQD
           @status = shell_out("ifconfig")
           @status.stdout.each_line do |line|
-            addr_regex = /^(\w+):?(\d*):?\ .+$/
+            addr_regex = /^((\w|-)+):?(\d*):?\ .+$/
             if line =~ addr_regex
               if line.match(addr_regex).nil?
                 @int_name = "nil"
-              elsif line.match(addr_regex)[2] == ""
+              elsif line.match(addr_regex)[3] == ""
                 @int_name = line.match(addr_regex)[1]
                 @interfaces[@int_name] = {}
                 @interfaces[@int_name]["mtu"] = (line =~ /mtu (\S+)/ ? Regexp.last_match(1) : "nil") if line =~ /mtu/ && @interfaces[@int_name]["mtu"].nil?
               else
-                @int_name = "#{line.match(addr_regex)[1]}:#{line.match(addr_regex)[2]}"
+                @int_name = "#{line.match(addr_regex)[1]}:#{line.match(addr_regex)[3]}"
                 @interfaces[@int_name] = {}
                 @interfaces[@int_name]["mtu"] = (line =~ /mtu (\S+)/ ? Regexp.last_match(1) : "nil") if line =~ /mtu/ && @interfaces[@int_name]["mtu"].nil?
               end

data/lib/chef/provider/package/chocolatey.rb

@@ -1,5 +1,5 @@
 #
-# Copyright:: Copyright 2015-2016, Chef Software, Inc.
+# Copyright:: Copyright 2015-2019, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -84,13 +84,13 @@ class Chef
 
           # choco does not support installing multiple packages with version pins
           name_has_versions.each do |name, version|
-            choco_command("install -y --version", version, cmd_args, name)
+            choco_command("install", "-y", "--version", version, cmd_args, name)
           end
 
           # but we can do all the ones without version pins at once
           unless name_nil_versions.empty?
             cmd_names = name_nil_versions.keys
-            choco_command("install -y", cmd_args, *cmd_names)
+            choco_command("install", "-y", cmd_args, *cmd_names)
           end
         end
 
@@ -106,13 +106,13 @@ class Chef
 
           # choco does not support installing multiple packages with version pins
           name_has_versions.each do |name, version|
-            choco_command("upgrade -y --version", version, cmd_args, name)
+            choco_command("upgrade", "-y", "--version", version, cmd_args, name)
           end
 
           # but we can do all the ones without version pins at once
           unless name_nil_versions.empty?
             cmd_names = name_nil_versions.keys
-            choco_command("upgrade -y", cmd_args, *cmd_names)
+            choco_command("upgrade", "-y", cmd_args, *cmd_names)
           end
         end
 
@@ -121,7 +121,7 @@ class Chef
         # @param names [Array<String>] array of package names to install
         # @param versions [Array<String>] array of versions to install
         def remove_package(names, versions)
-          choco_command("uninstall -y", cmd_args(include_source: false), *names)
+          choco_command("uninstall", "-y", cmd_args(include_source: false), *names)
         end
 
         # Choco does not have dpkg's distinction between purge and remove
@@ -172,7 +172,7 @@ class Chef
         # @param args [String] variable number of string arguments
         # @return [Mixlib::ShellOut] object returned from shell_out!
         def choco_command(*args)
-          shell_out!(args_to_string(choco_exe, *args), returns: new_resource.returns)
+          shell_out!(choco_exe, *args, returns: new_resource.returns)
         end
 
         # Use the available_packages Hash helper to create an array suitable for
@@ -210,18 +210,8 @@ class Chef
         # @return [String] options from new_resource or empty string
         def cmd_args(include_source: true)
           cmd_args = [ new_resource.options ]
-          cmd_args.push( "-source #{new_resource.source}" ) if new_resource.source && include_source
-          args_to_string(*cmd_args)
-        end
-
-        # Helper to nicely convert variable string args into a single command line.  It
-        # will compact nulls or empty strings and join arguments with single spaces, without
-        # introducing any double-spaces for missing args.
-        #
-        # @param args [String] variable number of string arguments
-        # @return [String] nicely concatenated string or empty string
-        def args_to_string(*args)
-          args.reject { |i| i.nil? || i == "" }.join(" ")
+          cmd_args.push([ "-source", new_resource.source ]) if new_resource.source && include_source
+          cmd_args
         end
 
         # Available packages in chocolatey as a Hash of names mapped to versions
@@ -236,8 +226,8 @@ class Chef
           package_name_array.each do |pkg|
             available_versions =
               begin
-                cmd = [ "list -r #{pkg}" ]
-                cmd.push( "-source #{new_resource.source}" ) if new_resource.source
+                cmd = [ "list", "-r", pkg ]
+                cmd.push( [ "-source", new_resource.source ] ) if new_resource.source
                 cmd.push( new_resource.options ) if new_resource.options
 
                 raw = parse_list_output(*cmd)
@@ -255,7 +245,7 @@ class Chef
         #
         # @return [Hash] name-to-version mapping of installed packages
         def installed_packages
-          @installed_packages ||= Hash[*parse_list_output("list -l -r").flatten]
+          @installed_packages ||= Hash[*parse_list_output("list", "-l", "-r").flatten]
           @installed_packages
         end
 

data/lib/chef/provider/user.rb

@@ -34,7 +34,7 @@ class Chef
       end
 
       def convert_group_name
-        if new_resource.gid.is_a? String
+        if new_resource.gid.is_a?(String) && new_resource.gid.to_i == 0
           new_resource.gid(Etc.getgrnam(new_resource.gid).gid)
         end
       rescue ArgumentError

data/lib/chef/provider/user/dscl.rb

@@ -42,7 +42,7 @@ class Chef
       #         => shadow binary length 128 bytes
       #         => Salt / Iterations are stored separately in the same file
       #
-      # This provider only supports Mac OSX versions 10.7 and above
+      # This provider only supports macOS versions 10.7 to 10.13
       class Dscl < Chef::Provider::User
 
         attr_accessor :user_info
@@ -50,7 +50,7 @@ class Chef
         attr_accessor :password_shadow_conversion_algorithm
 
         provides :dscl_user
-        provides :user, os: "darwin"
+        provides :user, os: "darwin", platform_version: "<= 10.13"
 
         # Just-in-case a recipe calls the user dscl provider without specifying
         # a gid property. Avoids chown issues in move_home when the manage_home

data/lib/chef/provider/user/mac.rb

@@ -0,0 +1,628 @@
+#
+# Author:: Ryan Cragun (<ryan@chef.io>)
+# Copyright:: Copyright (c) 2019, Chef Software Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative "../../resource"
+require_relative "../../dsl/declare_resource"
+require_relative "../../mixin/shell_out"
+require_relative "../../mixin/which"
+require_relative "../user"
+require_relative "../../resource/user/mac_user"
+
+class Chef
+  class Provider
+    class User
+      # A macOS user provider that is compatible with default TCC restrictions
+      # in macOS 10.14. See resource/user/mac_user.rb for complete description
+      # of the mac_user resource and how it differs from the dscl resource used
+      # on previous platforms.
+      class MacUser < Chef::Provider::User
+        include Chef::Mixin::Which
+
+        provides :mac_user
+        provides :user, os: "darwin", platform_version: ">= 10.14"
+
+        attr_reader :user_plist, :admin_group_plist
+
+        def load_current_resource
+          @current_resource = Chef::Resource::User::MacUser.new(new_resource.username)
+          current_resource.username(new_resource.username)
+
+          reload_admin_group_plist
+          reload_user_plist
+
+          if user_plist
+            current_resource.uid(user_plist[:uid][0])
+            current_resource.gid(user_plist[:gid][0])
+            current_resource.home(user_plist[:home][0])
+            current_resource.shell(user_plist[:shell][0])
+            current_resource.comment(user_plist[:comment][0])
+
+            shadow_hash = user_plist[:shadow_hash]
+            if shadow_hash
+              current_resource.password(shadow_hash[0]["SALTED-SHA512-PBKDF2"]["entropy"].string.unpack("H*")[0])
+              current_resource.salt(shadow_hash[0]["SALTED-SHA512-PBKDF2"]["salt"].string.unpack("H*")[0])
+              current_resource.iterations(shadow_hash[0]["SALTED-SHA512-PBKDF2"]["iterations"].to_i)
+            end
+
+            current_resource.secure_token(secure_token_enabled?)
+            current_resource.admin(admin_user?)
+          else
+            @user_exists = false
+            logger.trace("#{new_resource} user does not exist")
+          end
+
+          current_resource
+        end
+
+        def reload_admin_group_plist
+          @admin_group_plist = nil
+
+          admin_group_xml = run_dscl("read", "/Groups/admin")
+          return nil unless admin_group_xml && admin_group_xml != ""
+
+          @admin_group_plist = Plist.new(::Plist.parse_xml(admin_group_xml))
+        end
+
+        def reload_user_plist
+          @user_plist = nil
+
+          # Load the user information.
+          begin
+            user_xml = run_dscl("read", "/Users/#{new_resource.username}")
+          rescue Chef::Exceptions::DsclCommandFailed
+            return nil
+          end
+
+          return nil if user_xml.nil? || user_xml == ""
+
+          @user_plist = Plist.new(::Plist.parse_xml(user_xml))
+
+          shadow_hash_hex = user_plist[:shadow_hash][0]
+          return unless shadow_hash_hex && shadow_hash_hex != ""
+
+          # The password infomation is stored in the ShadowHashData key in the
+          # plist. However, parsing it is a bit tricky as the value is itself
+          # another encoded binary plist. We have to extract the encoded plist,
+          # decode it from hex to a binary plist and then convert the binary
+          # into XML plist. From there we can extract the hash data.
+          #
+          # NOTE: `dscl -read` and `plutil -convert` return different values for
+          # ShadowHashData.
+          #
+          # `dscl` returns the value encoded as a hex string and stored as a <string>
+          # `plutil` returns the value encoded as a base64 string stored as <data>
+          #
+          #  eg:
+          #
+          # <array>
+          #   <string>77687920 63616e27 74206170 706c6520 6275696c 6420636f 6e736973 74656e74 20746f6f 6c696e67</string>
+          # </array>
+          #
+          # vs
+          #
+          # <array>
+          #   <data>AADKAAAKAA4LAA0MAAAAAAAAAAA=</data>
+          # </array>
+          #
+          begin
+            shadow_binary_plist = [shadow_hash_hex.delete(" ")].pack("H*")
+            shadow_xml_plist = shell_out("plutil", "-convert", "xml1", "-o", "-", "-", input: shadow_binary_plist).stdout
+            user_plist[:shadow_hash] = ::Plist.parse_xml(shadow_xml_plist)
+          rescue Chef::Exceptions::PlistUtilCommandFailed, Chef::Exceptions::DsclCommandFailed
+            nil
+          end
+        end
+
+        #
+        # User Provider Callbacks
+        #
+
+        def create_user
+          cmd = [-"-addUser", new_resource.username]
+          cmd += ["-fullName", new_resource.comment] if prop_is_set?(:comment)
+          cmd += ["-UID", new_resource.uid]          if prop_is_set?(:uid)
+          cmd += ["-shell", new_resource.shell]
+          cmd += ["-home", new_resource.home]
+          cmd += ["-admin"] if new_resource.admin
+
+          # We can technically create a new user without the admin credentials
+          # but without them the user cannot enable SecureToken, thus they cannot
+          # create other secure users or enable FileVault full disk encryption.
+          if prop_is_set?(:admin_username) && prop_is_set?(:admin_password)
+            cmd += ["-adminUser", new_resource.admin_username]
+            cmd += ["-adminPassword", new_resource.admin_password]
+          end
+
+          converge_by "create user" do
+            # sysadminctl doesn't exit with a non-zero exit code if it encounters
+            # a problem. We'll check stderr and make sure we see that it finished
+            # correctly.
+            res = run_sysadminctl(cmd)
+            unless res.downcase =~ /creating user/
+              raise Chef::Exceptions::User, "error when creating user: #{res}"
+            end
+          end
+
+          # Wait for the user to show up in the ds cache
+          wait_for_user
+
+          # Reload with up-to-date user information
+          reload_user_plist
+          reload_admin_group_plist
+
+          if prop_is_set?(:password)
+            converge_by("set password") { set_password }
+          end
+
+          if new_resource.manage_home
+            # "sydadminctl -addUser" will create the home directory if it's
+            # the default /Users/<username>, otherwise it sets it in plist
+            # but does not create it. Here we'll ensure that it gets created
+            # if we've been given a directory that is not the default.
+            unless ::File.directory?(new_resource.home) && ::File.exist?(new_resource.home)
+              converge_by("create home directory") do
+                shell_out!("createhomedir -c -u #{new_resource.username}")
+              end
+            end
+          end
+
+          if prop_is_set?(:gid)
+            # NOTE: Here we're managing the primary group of the user which is
+            # a departure from previous behavior. We could just set the
+            # PrimaryGroupID for the user and move on if we decide that actual
+            # group magement should be done outside of the core resource.
+            group_name, group_id, group_action = user_group_info
+
+            declare_resource(:group, group_name) do
+              members new_resource.username
+              gid group_id if group_id
+              action :nothing
+              append true
+            end.run_action(group_action)
+
+            converge_by("create primary group ID") do
+              run_dscl("create", "/Users/#{new_resource.username}", "PrimaryGroupID", new_resource.gid)
+            end
+          end
+
+          if diverged?(:secure_token)
+            converge_by("alter SecureToken") { toggle_secure_token }
+          end
+
+          reload_user_plist
+        end
+
+        def compare_user
+          %i{comment shell uid gid salt password admin secure_token}.any? { |m| diverged?(m) }
+        end
+
+        def manage_user
+          %i{uid home}.each do |prop|
+            raise Chef::Exceptions::User, "cannot modify #{prop} on macOS >= 10.14" if diverged?(prop)
+          end
+
+          if diverged?(:password)
+            converge_by("alter password") { set_password }
+          end
+
+          if diverged?(:comment)
+            converge_by("alter comment") do
+              run_dscl("create", "/Users/#{new_resource.username}", "RealName", new_resource.comment)
+            end
+          end
+
+          if diverged?(:shell)
+            converge_by("alter shell") do
+              run_dscl("create", "/Users/#{new_resource.username}", "UserShell", new_resource.shell)
+            end
+          end
+
+          if diverged?(:secure_token)
+            converge_by("alter SecureToken") { toggle_secure_token }
+          end
+
+          if diverged?(:admin)
+            converge_by("alter admin group membership") do
+              declare_resource(:group, "admin") do
+                if new_resource.admin
+                  members new_resource.username
+                else
+                  excluded_members new_resource.username
+                end
+
+                action :nothing
+                append true
+              end.run_action(:create)
+
+              admins = admin_group_plist[:group_members]
+              if new_resource.admin
+                admins << user_plist[:guid][0]
+              else
+                admins.reject! { |m| m == user_plist[:guid][0] }
+              end
+
+              run_dscl("create", "/Groups/admin", "GroupMembers", admins)
+            end
+
+            reload_admin_group_plist
+          end
+
+          group_name, group_id, group_action = user_group_info
+          declare_resource(:group, group_name) do
+            gid group_id if group_id
+            members new_resource.username
+            action :nothing
+            append true
+          end.run_action(group_action)
+
+          if diverged?(:gid)
+            converge_by("alter group membership") do
+              run_dscl("create", "/Users/#{new_resource.username}", "PrimaryGroupID", new_resource.gid)
+            end
+          end
+
+          reload_user_plist
+        end
+
+        def remove_user
+          cmd = ["-deleteUser", new_resource.username]
+          cmd << new_resource.manage_home ? "-secure" : "-keepHome"
+          if %i{admin_username admin_password}.all? { |p| prop_is_set?(p) }
+            cmd += ["-adminUser", new_resource.admin_username]
+            cmd += ["-adminPassword", new_resource.admin_password]
+          end
+
+          # sysadminctl doesn't exit with a non-zero exit code if it encounters
+          # a problem. We'll check stderr and make sure we see that it finished
+          converge_by "remove user" do
+            res = run_sysadminctl(cmd)
+            unless res.downcase =~ /deleting record|not found/
+              raise Chef::Exceptions::User, "error deleting user: #{res}"
+            end
+          end
+
+          reload_user_plist
+          @user_exists = false
+        end
+
+        def lock_user
+          converge_by "lock user" do
+            run_dscl("append", "/Users/#{new_resource.username}", "AuthenticationAuthority", ";DisabledUser;")
+          end
+
+          reload_user_plist
+        end
+
+        def unlock_user
+          auth_string = user_plist[:auth_authority].reject! { |tag| tag == ";DisabledUser;" }.join.strip
+          converge_by "unlock user" do
+            run_dscl("create", "/Users/#{new_resource.username}", "AuthenticationAuthority", auth_string)
+          end
+
+          reload_user_plist
+        end
+
+        def locked?
+          user_plist[:auth_authority].any? { |tag| tag == ";DisabledUser;" }
+        rescue
+          false
+        end
+
+        def check_lock
+          @locked = locked?
+        end
+
+        #
+        # Methods
+        #
+
+        def diverged?(prop)
+          prop = prop.to_sym
+
+          case prop
+          when :password
+            password_diverged?
+          when :gid
+            user_group_diverged?
+          when :secure_token
+            secure_token_diverged?
+          else
+            # Other fields are have been set on current resource so just compare
+            # them.
+            !new_resource.send(prop).nil? && (new_resource.send(prop) != current_resource.send(prop))
+          end
+        end
+
+        # Attempt to resolve the group name, gid, and the action required for
+        # associated group resource. If a group exists we'll modify it, otherwise
+        # create it.
+        def user_group_info
+          @user_group_info ||= begin
+            if new_resource.gid.is_a?(String)
+              begin
+                g = Etc.getgrnam(new_resource.gid)
+                [g.name, g.gid.to_s, :modify]
+              rescue
+                [new_resource.gid, nil, :create]
+              end
+            else
+              begin
+                g = Etc.getgrgid(new_resource.gid)
+                [g.name, g.gid.to_s, :modify]
+              rescue
+                [g.username, nil, :create]
+              end
+            end
+          end
+        end
+
+        def secure_token_enabled?
+          user_plist[:auth_authority].any? { |tag| tag == ";SecureToken;" }
+        rescue
+          false
+        end
+
+        def secure_token_diverged?
+          new_resource.secure_token ? !secure_token_enabled? : secure_token_enabled?
+        end
+
+        def toggle_secure_token
+          # Check for this lazily as we only need to validate for these credentials
+          # if we're toggling secure token.
+          unless %i{admin_username admin_password secure_token_password}.all? { |p| prop_is_set?(p) }
+            raise Chef::Exceptions::User, "secure_token_password, admin_username and admin_password properties are required to modify SecureToken"
+          end
+
+          cmd = (new_resource.secure_token ? %w{-secureTokenOn} : %w{-secureTokenOff})
+          cmd += [new_resource.username, "-password", new_resource.secure_token_password]
+          cmd += ["-adminUser", new_resource.admin_username]
+          cmd += ["-adminPassword", new_resource.admin_password]
+
+          # sysadminctl doesn't exit with a non-zero exit code if it encounters
+          # a problem. We'll check stderr and make sure we see that it finished
+          res = run_sysadminctl(cmd)
+          unless res.downcase =~ /done/
+            raise Chef::Exceptions::User, "error when modifying SecureToken: #{res}"
+          end
+
+          # HACK: When SecureToken is enabled or disabled it requires the user
+          # password in plaintext, which it verifies and uses as a key. It also
+          # takes the liberty of _rehashing_ the password with a random salt and
+          # iterations count and saves it back into the user ShadowHashData.
+          #
+          # Therefore, if we're configuring a user based upon existing shadow
+          # hash data we'll have to set the password again so that future runs
+          # of the client don't show password drift.
+          set_password if prop_is_set?(:salt)
+        end
+
+        def user_group_diverged?
+          return false unless prop_is_set?(:gid)
+
+          group_name, group_id = user_group_info
+
+          if current_resource.gid.is_a?(String)
+            current_resource.gid != group_name
+          else
+            current_resource.gid != group_id.to_i
+          end
+        end
+
+        def password_diverged?
+          # There are three options for configuring the password:
+          #   * ShadowHashData which includes the hash data as:
+          #     * hashed entropy as the "password"
+          #     * salt
+          #     * iterations
+          #   * Plaintext password
+          #   * Not configuring it
+
+          # Check for no desired password configuration
+          return false unless prop_is_set?(:password)
+
+          # Check for ShadowHashData divergence by comparing the entropy,
+          # salt, and iterations.
+          if prop_is_set?(:salt)
+            return true if %i{salt iterations}.any? { |prop| diverged?(prop) }
+
+            return new_resource.password != current_resource.password
+          end
+
+          # Check for plaintext password divergence. We don't actually know
+          # what the stored password is but we can hash the given password with
+          # stored salt and iterations, and compare the resulting entropy with
+          # the saved entropy.
+          OpenSSL::PKCS5.pbkdf2_hmac(
+            new_resource.password,
+            convert_to_binary(current_resource.salt),
+            current_resource.iterations.to_i,
+            128,
+            OpenSSL::Digest::SHA512.new
+          ).unpack("H*")[0] != current_resource.password
+        end
+
+        def admin_user?
+          admin_group_plist[:group_members].any? { |mem| mem == user_plist[:guid][0] }
+        rescue
+          false
+        end
+
+        def convert_to_binary(string)
+          string.unpack("a2" * (string.size / 2)).collect { |i| i.hex.chr }.join
+        end
+
+        def set_password
+          if prop_is_set?(:salt)
+            entropy = StringIO.new(convert_to_binary(new_resource.password))
+            salt = StringIO.new(convert_to_binary(new_resource.salt))
+          else
+            salt = StringIO.new(OpenSSL::Random.random_bytes(32))
+            entropy = StringIO.new(
+              OpenSSL::PKCS5.pbkdf2_hmac(
+                new_resource.password,
+                salt.string,
+                new_resource.iterations,
+                128,
+                OpenSSL::Digest::SHA512.new
+              )
+            )
+          end
+
+          shadow_hash = user_plist[:shadow_hash][0]
+          shadow_hash["SALTED-SHA512-PBKDF2"] = {
+            "entropy" => entropy,
+            "salt" => salt,
+            "iterations" => new_resource.iterations,
+          }
+
+          shadow_hash_binary = StringIO.new
+          shell_out("plutil", "-convert", "binary1", "-o", "-", "-",
+            input: shadow_hash.to_plist,
+            live_stream: shadow_hash_binary)
+
+          # Apple seem to have killed their dsimport documentation about the
+          # dsimport record format. Perhaps that means our days of being able to
+          # use dsimport without an admin password or perhaps at all could be
+          # numbered. Here is the record format for posterity:
+          #
+          # End of record character
+          # Escape character
+          # Field separator
+          # Value separator
+          # Record type (Users, Groups, Computers, ComputerGroups, ComputerLists)
+          # Number of properties
+          # Property 1
+          # ...
+          # Property N
+          #
+          # The user password shadow data format breaks down as:
+          #
+          # 0x0A                                    End of record denoted by \n
+          # 0x5C                                    Escaping is denoted by \
+          # 0x3A                                    Fields are separated by :
+          # 0x2C                                    Values are seperated by ,
+          # dsRecTypeStandard:Users                 The record type we're configuring
+          # 2                                       How many properties we're going to set
+          # dsAttrTypeStandard:RecordName           Property 1: our users record name
+          # base64:dsAttrTypeNative:ShadowHashData  Property 2: our shadow hash data
+
+          import_file = ::File.join(Chef::Config["file_cache_path"], "#{new_resource.username}_password_dsimport")
+          ::File.open(import_file, "w+", 0600) do |f|
+            f.write <<~DSIMPORT
+              0x0A 0x5C 0x3A 0x2C dsRecTypeStandard:Users 2 dsAttrTypeStandard:RecordName base64:dsAttrTypeNative:ShadowHashData
+              #{new_resource.username}:#{::Base64.strict_encode64(shadow_hash_binary.string)}
+            DSIMPORT
+          end
+
+          run_dscl("delete", "/Users/#{new_resource.username}", "ShadowHashData")
+          run_dsimport(import_file, "/Local/Default", "M")
+          run_dscl("create", "/Users/#{new_resource.username}", "Password", "********")
+        ensure
+          ::File.delete(import_file) if defined?(import_file) && ::File.exist?(import_file)
+        end
+
+        def wait_for_user
+          timeout = Time.now + 5
+
+          loop do
+            begin
+              run_dscl("read", "/Users/#{new_resource.username}", "ShadowHashData")
+              break
+            rescue Chef::Exceptions::DsclCommandFailed => e
+              if Time.now < timeout
+                sleep 0.1
+              else
+                raise Chef::Exceptions::User, e.message
+              end
+            end
+          end
+        end
+
+        def run_dsimport(*args)
+          shell_out!("dsimport", args)
+        end
+
+        def run_sysadminctl(args)
+          # sysadminctl doesn't exit with a non-zero code when errors are encountered
+          # and ouputs everything to STDERR instead of STDOUT and STDERR. Therefore we'll
+          # return the STDERR and let the caller handle it.
+          shell_out!("sysadminctl", args).stderr
+        end
+
+        def run_dscl(*args)
+          result = shell_out("dscl", "-plist", ".", "-#{args[0]}", args[1..-1])
+          return "" if ( args.first =~ /^delete/ ) && ( result.exitstatus != 0 )
+          raise(Chef::Exceptions::DsclCommandFailed, "dscl error: #{result.inspect}") unless result.exitstatus == 0
+          raise(Chef::Exceptions::DsclCommandFailed, "dscl error: #{result.inspect}") if result.stdout =~ /No such key: /
+
+          result.stdout
+        end
+
+        def run_plutil(*args)
+          result = shell_out("plutil", "-#{args[0]}", args[1..-1])
+          raise(Chef::Exceptions::PlistUtilCommandFailed, "plutil error: #{result.inspect}") unless result.exitstatus == 0
+
+          result.stdout
+        end
+
+        def prop_is_set?(prop)
+          v = new_resource.send(prop.to_sym)
+
+          !v.nil? && v != ""
+        end
+
+        class Plist
+          DSCL_PROPERTY_MAP = {
+              uid: "dsAttrTypeStandard:UniqueID",
+              guid: "dsAttrTypeStandard:GeneratedUID",
+              gid: "dsAttrTypeStandard:PrimaryGroupID",
+              home: "dsAttrTypeStandard:NFSHomeDirectory",
+              shell: "dsAttrTypeStandard:UserShell",
+              comment: "dsAttrTypeStandard:RealName",
+              password: "dsAttrTypeStandard:Password",
+              auth_authority: "dsAttrTypeStandard:AuthenticationAuthority",
+              shadow_hash: "dsAttrTypeNative:ShadowHashData",
+              group_members: "dsAttrTypeStandard:GroupMembers",
+          }.freeze
+
+          attr_accessor :plist_hash, :property_map
+
+          def initialize(plist_hash = {}, property_map = DSCL_PROPERTY_MAP)
+            @plist_hash = plist_hash
+            @property_map = property_map
+          end
+
+          def get(key)
+            return nil unless property_map.key?(key)
+
+            plist_hash[property_map[key]]
+          end
+          alias_method :[], :get
+
+          def set(key, value)
+            return nil unless property_map.key?(key)
+
+            plist_hash[property_map[key]] = [ value ]
+          end
+          alias_method :[]=, :set
+
+        end
+      end
+    end
+  end
+end