require_relative '../../../puppet'
require_relative '../../../puppet/util/plist' if Puppet.features.cfpropertylist?
require 'base64'

Puppet::Type.type(:user).provide :directoryservice do
  desc "User management on OS X."

##                   ##
## Provider Settings ##
##                   ##

  # Provider command declarations
  commands :uuidgen      => '/usr/bin/uuidgen'
  commands :dsimport     => '/usr/bin/dsimport'
  commands :dscl         => '/usr/bin/dscl'
  commands :dscacheutil  => '/usr/bin/dscacheutil'

  # Provider confines and defaults
  confine    :operatingsystem => :darwin
  confine    :feature         => :cfpropertylist
  defaultfor :operatingsystem => :darwin

  # Need this to create getter/setter methods automagically
  # This command creates methods that return @property_hash[:value]
  mk_resource_methods

  # JJM: OS X can manage passwords.
  has_feature :manages_passwords

  # 10.8 Passwords use a PBKDF2 salt value
  has_features :manages_password_salt

  #provider can set the user's shell
  has_feature :manages_shell

##               ##
## Class Methods ##
##               ##

  # This method exists to map the dscl values to the correct Puppet
  # properties. This stays relatively consistent, but who knows what
  # Apple will do next year...
  def self.ds_to_ns_attribute_map
    {
      'RecordName'       => :name,
      'PrimaryGroupID'   => :gid,
      'NFSHomeDirectory' => :home,
      'UserShell'        => :shell,
      'UniqueID'         => :uid,
      'RealName'         => :comment,
      'Password'         => :password,
      'GeneratedUID'     => :guid,
      'IPAddress'        => :ip_address,
      'ENetAddress'      => :en_address,
      'GroupMembership'  => :members,
    }
  end

  def self.ns_to_ds_attribute_map
    @ns_to_ds_attribute_map ||= ds_to_ns_attribute_map.invert
  end

  # Prefetching is necessary to use @property_hash inside any setter methods.
  # self.prefetch uses self.instances to gather an array of user instances
  # on the system, and then populates the @property_hash instance variable
  # with attribute data for the specific instance in question (i.e. it
  # gathers the 'is' values of the resource into the @property_hash instance
  # variable so you don't have to read from the system every time you need
  # to gather the 'is' values for a resource. The downside here is that
  # populating this instance variable for every resource on the system
  # takes time and front-loads your Puppet run.
  def self.prefetch(resources)
    instances.each do |prov|
      resource = resources[prov.name]
      if resource
        resource.provider = prov
      end
    end
  end

  # This method assembles an array of provider instances containing
  # information about every instance of the user type on the system (i.e.
  # every user and its attributes). The `puppet resource` command relies
  # on self.instances to gather an array of user instances in order to
  # display its output.
  def self.instances
    get_all_users.collect do |user|
      self.new(generate_attribute_hash(user))
    end
  end

  # Return an array of hashes containing information about every user on
  # the system.
  def self.get_all_users
    Puppet::Util::Plist.parse_plist(dscl '-plist', '.', 'readall', '/Users')
  end

  # This method accepts an individual user plist, passed as a hash, and
  # strips the dsAttrTypeStandard: prefix that dscl adds for each key.
  # An attribute hash is assembled and returned from the properties
  # supported by the user type.
  def self.generate_attribute_hash(input_hash)
    attribute_hash = {}
    input_hash.each_key do |key|
      ds_attribute = key.sub("dsAttrTypeStandard:", "")
      next unless ds_to_ns_attribute_map.keys.include?(ds_attribute)
      ds_value = input_hash[key]
      case ds_to_ns_attribute_map[ds_attribute]
        when :gid, :uid
          # OS X stores objects like uid/gid as strings.
          # Try casting to an integer for these cases to be
          # consistent with the other providers and the group type
          # validation
          begin
            ds_value = Integer(ds_value[0])
          rescue ArgumentError
            ds_value = ds_value[0]
          end
        else ds_value = ds_value[0]
      end
      attribute_hash[ds_to_ns_attribute_map[ds_attribute]] = ds_value
    end
    attribute_hash[:ensure]         = :present
    attribute_hash[:provider]       = :directoryservice
    attribute_hash[:shadowhashdata] = input_hash['dsAttrTypeNative:ShadowHashData']

    ##############
    # Get Groups #
    ##############
    groups_array = []
    get_list_of_groups.each do |group|
      if group["dsAttrTypeStandard:GroupMembership"] and group["dsAttrTypeStandard:GroupMembership"].include?(attribute_hash[:name])
        groups_array << group["dsAttrTypeStandard:RecordName"][0]
      end

      if group["dsAttrTypeStandard:GroupMembers"] and group["dsAttrTypeStandard:GroupMembers"].include?(attribute_hash[:guid])
        groups_array << group["dsAttrTypeStandard:RecordName"][0]
      end
    end
    attribute_hash[:groups] = groups_array.uniq.sort.join(',')

    ################################
    # Get Password/Salt/Iterations #
    ################################
    if attribute_hash[:shadowhashdata].nil? or attribute_hash[:shadowhashdata].empty?
      attribute_hash[:password] = '*'
    else
      embedded_binary_plist = get_embedded_binary_plist(attribute_hash[:shadowhashdata])
      if embedded_binary_plist['SALTED-SHA512-PBKDF2']
        attribute_hash[:password]   = get_salted_sha512_pbkdf2('entropy', embedded_binary_plist, attribute_hash[:name])
        attribute_hash[:salt]       = get_salted_sha512_pbkdf2('salt', embedded_binary_plist, attribute_hash[:name])
        attribute_hash[:iterations] = get_salted_sha512_pbkdf2('iterations', embedded_binary_plist, attribute_hash[:name])
      elsif embedded_binary_plist['SALTED-SHA512']
        attribute_hash[:password] = get_salted_sha512(embedded_binary_plist)
      end
    end

    attribute_hash
  end

  def self.get_os_version
    @os_version ||= Puppet.runtime[:facter].value(:macosx_productversion_major)
  end

  # Use dscl to retrieve an array of hashes containing attributes about all
  # of the local groups on the machine.
  def self.get_list_of_groups
    @groups ||= Puppet::Util::Plist.parse_plist(dscl '-plist', '.', 'readall', '/Groups')
  end

  # Perform a dscl lookup at the path specified for the specific keyname
  # value. The value returned is the first item within the array returned
  # from dscl
  def self.get_attribute_from_dscl(path, username, keyname)
    Puppet::Util::Plist.parse_plist(dscl '-plist', '.', 'read', "/#{path}/#{username}", keyname)
  end

  # The plist embedded in the ShadowHashData key is a binary plist. The
  # plist library doesn't read binary plists, so we need to
  # extract the binary plist, convert it to XML, and return it.
  def self.get_embedded_binary_plist(shadow_hash_data)
    embedded_binary_plist = Array(shadow_hash_data[0].delete(' ')).pack('H*')
    convert_binary_to_hash(embedded_binary_plist)
  end

  # This method will accept a hash and convert it to a binary plist (string value).
  def self.convert_hash_to_binary(plist_data)
    Puppet.debug('Converting plist hash to binary')
    Puppet::Util::Plist.dump_plist(plist_data, :binary)
  end

  # This method will accept a binary plist (as a string) and convert it to a hash.
  def self.convert_binary_to_hash(plist_data)
    Puppet.debug('Converting binary plist to hash')
    Puppet::Util::Plist.parse_plist(plist_data)
  end

  # The salted-SHA512 password hash in 10.7 is stored in the 'SALTED-SHA512'
  # key as binary data. That data is extracted and converted to a hex string.
  def self.get_salted_sha512(embedded_binary_plist)
    embedded_binary_plist['SALTED-SHA512'].unpack("H*")[0]
  end

  # This method reads the passed embedded_binary_plist hash and returns values
  # according to which field is passed.  Arguments passed are the hash
  # containing the value read from the 'ShadowHashData' key in the User's
  # plist, and the field to be read (one of 'entropy', 'salt', or 'iterations')
  def self.get_salted_sha512_pbkdf2(field, embedded_binary_plist, user_name = "")
    case field
    when 'salt', 'entropy'
      value = embedded_binary_plist['SALTED-SHA512-PBKDF2'][field]
      if value == nil
        raise Puppet::Error, "Invalid #{field} given for user #{user_name}"
      end
      value.unpack('H*').first
    when 'iterations'
      Integer(embedded_binary_plist['SALTED-SHA512-PBKDF2'][field])
    else
      raise Puppet::Error, "Puppet has tried to read an incorrect value from the user #{user_name} in the SALTED-SHA512-PBKDF2 hash. Acceptable fields are 'salt', 'entropy', or 'iterations'."
    end
  end

  # In versions 10.5 and 10.6 of OS X, the password hash is stored in a file
  # in the /var/db/shadow/hash directory that matches the GUID of the user.
  def self.get_sha1(guid)
    password_hash = nil
    password_hash_file = "#{password_hash_dir}/#{guid}"
    if Puppet::FileSystem.exist?(password_hash_file) and File.file?(password_hash_file)
      raise Puppet::Error, "Could not read password hash file at #{password_hash_file}" if not File.readable?(password_hash_file)
      f = File.new(password_hash_file)
      password_hash = f.read
      f.close
    end
    password_hash
  end


##                   ##
## Ensurable Methods ##
##                   ##

  def exists?
    begin
      dscl '.', 'read', "/Users/#{@resource.name}"
    rescue Puppet::ExecutionFailure => e
      Puppet.debug("User was not found, dscl returned: #{e.inspect}")
      return false
    end
    true
  end

  # This method is called if ensure => present is passed and the exists?
  # method returns false. Dscl will directly set most values, but the
  # setter methods will be used for any exceptions.
  def create
    create_new_user(@resource.name)

    # Retrieve the user's GUID
    @guid = self.class.get_attribute_from_dscl('Users', @resource.name, 'GeneratedUID')['dsAttrTypeStandard:GeneratedUID'][0]

    # Get an array of valid User type properties
    valid_properties = Puppet::Type.type('User').validproperties

    # Iterate through valid User type properties
    valid_properties.each do |attribute|
      next if attribute == :ensure
      value = @resource.should(attribute)

      # Value defaults
      if value.nil?
        value = case attribute
                when :gid
                  '20'
                when :uid
                  next_system_id
                when :comment
                  @resource.name
                when :shell
                  '/bin/bash'
                when :home
                  "/Users/#{@resource.name}"
                else
                  nil
                end
      end

      # Ensure group names are converted to integers.
      value = Puppet::Util.gid(value) if attribute == :gid

      ## Set values ##
      # For the :password and :groups properties, call the setter methods
      # to enforce those values. For everything else, use dscl with the
      # ns_to_ds_attribute_map to set the appropriate values.
      if value != "" and not value.nil?
        case attribute
        when :password
          self.password = value
        when :iterations
          self.iterations = value
        when :salt
          self.salt = value
        when :groups
          value.split(',').each do |group|
            merge_attribute_with_dscl('Groups', group, 'GroupMembership', @resource.name)
            merge_attribute_with_dscl('Groups', group, 'GroupMembers', @guid)
          end
        else
          create_attribute_with_dscl('Users', @resource.name, self.class.ns_to_ds_attribute_map[attribute], value)
        end
      end
    end
  end

  # This method is called when ensure => absent has been set.
  # Deleting a user is handled by dscl
  def delete
    dscl '.', '-delete', "/Users/#{@resource.name}"
  end

##                       ##
## Getter/Setter Methods ##
##                       ##

  # In the setter method we're only going to take action on groups for which
  # the user is not currently a member.
  def groups=(value)
    guid = self.class.get_attribute_from_dscl('Users', @resource.name, 'GeneratedUID')['dsAttrTypeStandard:GeneratedUID'][0]
    groups_to_add = value.split(',') - groups.split(',')
    groups_to_add.each do |group|
      merge_attribute_with_dscl('Groups', group, 'GroupMembership', @resource.name)
      merge_attribute_with_dscl('Groups', group, 'GroupMembers', guid)
    end
  end

  # If you thought GETTING a password was bad, try SETTING it. This method
  # makes me want to cry. A thousand tears...
  #
  # I've been unsuccessful in tracking down a way to set the password for
  # a user using dscl that DOESN'T require passing it as plaintext. We were
  # also unable to get dsimport to work like this. Due to these downfalls,
  # the sanest method requires opening the user's plist, dropping in the
  # password hash, and serializing it back to disk. The problems with THIS
  # method revolve around dscl. Any time you directly modify a user's plist,
  # you need to flush the cache that dscl maintains.
  def password=(value)
    if self.class.get_os_version == '10.7'
      if value.length != 136
        raise Puppet::Error, "OS X 10.7 requires a Salted SHA512 hash password of 136 characters.  Please check your password and try again."
      end
    else
      if value.length != 256
         raise Puppet::Error, "OS X versions > 10.7 require a Salted SHA512 PBKDF2 password hash of 256 characters. Please check your password and try again."
      end

      assert_full_pbkdf2_password
    end

    # Methods around setting the password on OS X are the ONLY methods that
    # cannot use dscl (because the only way to set it via dscl is by passing
    # a plaintext password - which is bad). Because of this, we have to change
    # the user's plist directly. DSCL has its own caching mechanism, which
    # means that every time we call dscl in this provider we're not directly
    # changing values on disk (instead, those calls are cached and written
    # to disk according to Apple's prioritization algorithms). When Puppet
    # needs to set the password property on OS X > 10.6, the provider has to
    # tell dscl to write its cache to disk before modifying the user's
    # plist. The 'dscacheutil -flushcache' command does this. Another issue
    # is how fast Puppet makes calls to dscl and how long it takes dscl to
    # enter those calls into its cache. We have to sleep for 2 seconds before
    # flushing the dscl cache to allow all dscl calls to get INTO the cache
    # first. This could be made faster (and avoid a sleep call) by finding
    # a way to enter calls into the dscl cache faster. A sleep time of 1
    # second would intermittently require a second Puppet run to set
    # properties, so 2 seconds seems to be the minimum working value.
    sleep 2
    flush_dscl_cache
    write_password_to_users_plist(value)

    # Since we just modified the user's plist, we need to flush the ds cache
    # again so dscl can pick up on the changes we made.
    flush_dscl_cache
  end

  # The iterations and salt properties, like the password property, can only
  # be modified by directly changing the user's plist. Because of this fact,
  # we have to treat the ds cache just like you would in the password=
  # method.
  def iterations=(value)
    if (Puppet::Util::Package.versioncmp(self.class.get_os_version, '10.7') > 0)
      assert_full_pbkdf2_password

      sleep 3
      flush_dscl_cache
      users_plist = get_users_plist(@resource.name)
      shadow_hash_data = get_shadow_hash_data(users_plist)
      set_salted_pbkdf2(users_plist, shadow_hash_data, 'iterations', value)
      flush_dscl_cache
    end
  end

  # The iterations and salt properties, like the password property, can only
  # be modified by directly changing the user's plist. Because of this fact,
  # we have to treat the ds cache just like you would in the password=
  # method.
  def salt=(value)
    if (Puppet::Util::Package.versioncmp(self.class.get_os_version, '10.15') >= 0)
      if value.length != 64
        self.fail "macOS versions 10.15 and higher require the salt to be 32-bytes. Since Puppet's user resource requires the value to be hex encoded, the length of the salt's string must be 64. Please check your salt and try again."
      end
    end
    if (Puppet::Util::Package.versioncmp(self.class.get_os_version, '10.7') > 0)
      assert_full_pbkdf2_password

      sleep 3
      flush_dscl_cache
      users_plist = get_users_plist(@resource.name)
      shadow_hash_data = get_shadow_hash_data(users_plist)
      set_salted_pbkdf2(users_plist, shadow_hash_data, 'salt', value)
      flush_dscl_cache
    end
  end

  #####
  # Dynamically create setter methods for dscl properties
  #####
  #
  # Setter methods are only called when a resource currently has a value for
  # that property and it needs changed (true here since all of these values
  # have a default that is set in the create method). We don't want to merge
  # in additional values if an incorrect value is set, we want to CHANGE it.
  # When using the -change argument in dscl, the old value needs to be passed
  # first (followed by the new value). Because of this, we get the current
  # value from the @property_hash variable and then use the value passed as
  # the new value. Because we're prefetching instances of the provider, it's
  # possible that the value determined at the start of the run may be stale
  # (i.e. someone changed the value by hand during a Puppet run) - if that's
  # the case we rescue the error from dscl and alert the user.
  #
  # In the event that the user doesn't HAVE a value for the attribute, the
  # provider should use the -create option with dscl to add the attribute value
  # for the user record
  ['home', 'uid', 'gid', 'comment', 'shell'].each do |setter_method|
    define_method("#{setter_method}=") do |value|
      if @property_hash[setter_method.intern]
        if %w(home uid).include?(setter_method)
          raise Puppet::Error, "OS X version #{self.class.get_os_version} does not allow changing #{setter_method} using puppet"
        end
        begin
          dscl '.', '-change', "/Users/#{resource.name}", self.class.ns_to_ds_attribute_map[setter_method.intern], @property_hash[setter_method.intern], value
        rescue Puppet::ExecutionFailure => e
          raise Puppet::Error, "Cannot set the #{setter_method} value of '#{value}' for user " +
               "#{@resource.name} due to the following error: #{e.inspect}", e.backtrace
        end
      else
        begin
          dscl '.', '-create', "/Users/#{resource.name}", self.class.ns_to_ds_attribute_map[setter_method.intern], value
        rescue Puppet::ExecutionFailure => e
          raise Puppet::Error, "Cannot set the #{setter_method} value of '#{value}' for user " +
               "#{@resource.name} due to the following error: #{e.inspect}", e.backtrace
        end
      end
    end
  end


  ##                ##
  ## Helper Methods ##
  ##                ##

  def assert_full_pbkdf2_password
    missing = [:password, :salt, :iterations].select { |parameter| @resource[parameter].nil? }

    if !missing.empty?
       raise Puppet::Error, "OS X versions > 10\.7 use PBKDF2 password hashes, which requires all three of salt, iterations, and password hash. This resource is missing: #{missing.join(', ')}."
    end
  end

  def users_plist_dir
    '/var/db/dslocal/nodes/Default/users'
  end

  def self.password_hash_dir
    '/var/db/shadow/hash'
  end

  # This method will create a given value using dscl
  def create_attribute_with_dscl(path, username, keyname, value)
    set_attribute_with_dscl('-create', path, username, keyname, value)
  end

  # This method will merge in a given value using dscl
  def merge_attribute_with_dscl(path, username, keyname, value)
    set_attribute_with_dscl('-merge', path, username, keyname, value)
  end

  def set_attribute_with_dscl(dscl_command, path, username, keyname, value)
    begin
      dscl '.', dscl_command, "/#{path}/#{username}", keyname, value
    rescue Puppet::ExecutionFailure => detail
      raise Puppet::Error, "Could not set the dscl #{keyname} key with value: #{value} - #{detail.inspect}", detail.backtrace
    end
  end

  # Create the new user with dscl
  def create_new_user(username)
    dscl '.', '-create',  "/Users/#{username}"
  end

  # Get the next available uid on the system by getting a list of user ids,
  # sorting them, grabbing the last one, and adding a 1. Scientific stuff here.
  def next_system_id(min_id=20)
    dscl_output = dscl '.', '-list', '/Users', 'uid'
    # We're ok with throwing away negative uids here. Also, remove nil values.
    user_ids = dscl_output.split.compact.collect { |l| l.to_i if l =~ /^\d+$/ }
    ids = user_ids.compact!.sort! { |a,b| a.to_f <=> b.to_f }
    # We're just looking for an unused id in our sorted array.
    ids.each_index do |i|
      next_id = ids[i] + 1
      return next_id if ids[i+1] != next_id and next_id >= min_id
    end
  end

  # This method is only called on version 10.7 or greater. On 10.7 machines,
  # passwords are set using a salted-SHA512 hash, and on 10.8 machines,
  # passwords are set using PBKDF2. It's possible to have users on 10.8
  # who have upgraded from 10.7 and thus have a salted-SHA512 password hash.
  # If we encounter this, do what 10.8 does - remove that key and give them
  # a 10.8-style PBKDF2 password.
  def write_password_to_users_plist(value)
    users_plist = get_users_plist(@resource.name)
    shadow_hash_data = get_shadow_hash_data(users_plist)
    if self.class.get_os_version == '10.7'
      set_salted_sha512(users_plist, shadow_hash_data, value)
    else
      # It's possible that a user could exist on the system and NOT have
      # a ShadowHashData key (especially if the system was upgraded from 10.6).
      # In this case, a conditional check is needed to determine if the
      # shadow_hash_data variable is a Hash (it would be false if the key
      # didn't exist for this user on the system). If the shadow_hash_data
      # variable IS a Hash and contains the 'SALTED-SHA512' key (indicating an
      # older 10.7-style password hash), it will be deleted and a newer
      # 10.8-style (PBKDF2) password hash will be generated.
      if (shadow_hash_data.class == Hash) && (shadow_hash_data.has_key?('SALTED-SHA512'))
        shadow_hash_data.delete('SALTED-SHA512')
      end

      # Starting with macOS 11 Big Sur, the AuthenticationAuthority field
      # could be missing entirely and without it the managed user cannot log in
      if needs_sha512_pbkdf2_authentication_authority_to_be_added?(users_plist)
        Puppet.debug("Adding 'SALTED-SHA512-PBKDF2' AuthenticationAuthority key for ShadowHash to user '#{@resource.name}'")
        merge_attribute_with_dscl('Users', @resource.name, 'AuthenticationAuthority', ERB::Util.html_escape(SHA512_PBKDF2_AUTHENTICATION_AUTHORITY))
      end

      set_salted_pbkdf2(users_plist, shadow_hash_data, 'entropy', value)
    end
  end

  def flush_dscl_cache
    dscacheutil '-flushcache'
  end

  def get_users_plist(username)
    # This method will retrieve the data stored in a user's plist and
    # return it as a native Ruby hash.
    path = "#{users_plist_dir}/#{username}.plist"
    Puppet::Util::Plist.read_plist_file(path)
  end

  # This method will return the binary plist that's embedded in the
  # ShadowHashData key of a user's plist, or false if it doesn't exist.
  def get_shadow_hash_data(users_plist)
    if users_plist['ShadowHashData']
      password_hash_plist  = users_plist['ShadowHashData'][0]
      self.class.convert_binary_to_hash(password_hash_plist)
    else
      false
    end
  end

  # This method will check if authentication_authority key of a user's plist
  # needs SALTED_SHA512_PBKDF2 to be added. This is a valid case for macOS 11 (Big Sur)
  # where users created with `dscl` started to have this field missing
  def needs_sha512_pbkdf2_authentication_authority_to_be_added?(users_plist)
    authority = users_plist['authentication_authority']
    return false if Puppet::Util::Package.versioncmp(self.class.get_os_version, '11.0.0') < 0 && authority && authority.include?(SHA512_PBKDF2_AUTHENTICATION_AUTHORITY)

    Puppet.debug("User '#{@resource.name}' is missing the 'SALTED-SHA512-PBKDF2' AuthenticationAuthority key for ShadowHash")
    true
  end

  # This method will embed the binary plist data comprising the user's
  # password hash (and Salt/Iterations value if the OS is 10.8 or greater)
  # into the ShadowHashData key of the user's plist.
  def set_shadow_hash_data(users_plist, binary_plist)
    binary_plist = Puppet::Util::Plist.string_to_blob(binary_plist)
    if users_plist.has_key?('ShadowHashData')
      users_plist['ShadowHashData'][0] = binary_plist
    else
      users_plist['ShadowHashData'] = [binary_plist]
    end
    write_and_import_shadow_hash_data(users_plist['ShadowHashData'].first)
  end

  # This method writes the ShadowHashData plist in a temporary file,
  # then imports it using dsimport. macOS versions 10.15 and newer do
  # not support directly managing binary plists, so we have to use an
  # intermediary.
  # dsimport is an archaic utilitary with hard-to-find documentation
  #
  # See http://web.archive.org/web/20090106120111/http://support.apple.com/kb/TA21305?viewlocale=en_US
  # for information regarding the dsimport syntax
  def write_and_import_shadow_hash_data(data_plist)
    Tempfile.create("dsimport_#{@resource.name}", :encoding => Encoding::ASCII) do |dsimport_file|
      dsimport_file.write <<-DSIMPORT
0x0A 0x5C 0x3A 0x2C dsRecTypeStandard:Users 2 dsAttrTypeStandard:RecordName base64:dsAttrTypeNative:ShadowHashData
#{@resource.name}:#{Base64.strict_encode64(data_plist)}
      DSIMPORT
      dsimport_file.flush
      # Delete the user's existing ShadowHashData, since dsimport appends, not replaces
      dscl('.', 'delete', "/Users/#{@resource.name}", 'ShadowHashData')
      dsimport(dsimport_file.path, '/Local/Default', 'M')
    end
  end

  # This method accepts an argument of a hex password hash, and base64
  # decodes it into a format that OS X 10.7 and 10.8 will store
  # in the user's plist.
  def base64_decode_string(value)
    Base64.decode64([[value].pack("H*")].pack("m").strip)
  end

  # Puppet requires a salted-sha512 password hash for 10.7 users to be passed
  # in Hex, but the embedded plist stores that value as a Base64 encoded
  # string. This method converts the string and calls the
  # set_shadow_hash_data method to serialize and write the plist to disk.
  def set_salted_sha512(users_plist, shadow_hash_data, value)
    unless shadow_hash_data
      shadow_hash_data = Hash.new
      shadow_hash_data['SALTED-SHA512'] = ''
    end
    shadow_hash_data['SALTED-SHA512'] = base64_decode_string(value)
    binary_plist = self.class.convert_hash_to_binary(shadow_hash_data)
    set_shadow_hash_data(users_plist, binary_plist)
  end

  # This method accepts a passed value and one of three fields: 'salt',
  # 'entropy', or 'iterations'.  These fields correspond with the fields
  # utilized in a PBKDF2 password hashing system
  # (see https://en.wikipedia.org/wiki/PBKDF2 ) where 'entropy' is the
  # password hash, 'salt' is the password hash salt value, and 'iterations'
  # is an integer recommended to be > 10,000. The remaining arguments are
  # the user's plist itself, and the shadow_hash_data hash containing the
  # existing PBKDF2 values.
  def set_salted_pbkdf2(users_plist, shadow_hash_data, field, value)
    shadow_hash_data = Hash.new unless shadow_hash_data
    shadow_hash_data['SALTED-SHA512-PBKDF2'] = Hash.new unless shadow_hash_data['SALTED-SHA512-PBKDF2']
    case field
    when 'salt', 'entropy'
      shadow_hash_data['SALTED-SHA512-PBKDF2'][field] = Puppet::Util::Plist.string_to_blob(base64_decode_string(value))
    when 'iterations'
      shadow_hash_data['SALTED-SHA512-PBKDF2'][field] = Integer(value)
    else
      raise Puppet::Error "Puppet has tried to set an incorrect field for the 'SALTED-SHA512-PBKDF2' hash. Acceptable fields are 'salt', 'entropy', or 'iterations'."
    end

    # on 10.8, this field *must* contain 8 stars, or authentication will
    # fail.
    users_plist['passwd'] = ('*' * 8)

    # Convert shadow_hash_data to a binary plist, and call the
    # set_shadow_hash_data method to serialize and write the data
    # back to the user's plist.
    binary_plist = self.class.convert_hash_to_binary(shadow_hash_data)
    set_shadow_hash_data(users_plist, binary_plist)
  end

  private

  SHA512_PBKDF2_AUTHENTICATION_AUTHORITY = ';ShadowHash;HASHLIST:<SALTED-SHA512-PBKDF2,SRP-RFC5054-4096-SHA512-PBKDF2>'
end