# frozen_string_literal: true 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 'os.name' => :darwin confine :feature => :cfpropertylist defaultfor 'os.name' => :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('os.macosx.version.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'] = ''.dup 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:' end