Module: Puppet::Util::Windows::Security

Extended by:
FFI::Library, Security
Includes:
String
Included in:
Security
Defined in:
lib/puppet/util/windows/security.rb

Defined Under Namespace

Classes: ACE_HEADER, ACL, GENERIC_ACCESS_ACE

Constant Summary collapse

S_IRUSR =

file modes

0o000400
S_IRGRP = 
0o000040
S_IROTH = 
0o000004
S_IWUSR = 
0o000200
S_IWGRP = 
0o000020
S_IWOTH = 
0o000002
S_IXUSR = 
0o000100
S_IXGRP = 
0o000010
S_IXOTH = 
0o000001
S_IRWXU = 
0o000700
S_IRWXG = 
0o000070
S_IRWXO = 
0o000007
S_ISVTX = 
0o001000
S_IEXTRA =

represents an extra ace

0o2000000
S_ISYSTEM_MISSING = 
0o4000000
PROTECTED_DACL_SECURITY_INFORMATION =

constants that are missing from Windows::Security

0x80000000
UNPROTECTED_DACL_SECURITY_INFORMATION = 
0x20000000
NO_INHERITANCE = 
0x0
SE_DACL_PROTECTED = 
0x1000
FILE = 
Puppet::Util::Windows::File
SE_BACKUP_NAME = 
'SeBackupPrivilege'
SE_DEBUG_NAME = 
'SeDebugPrivilege'
SE_RESTORE_NAME = 
'SeRestorePrivilege'
DELETE = 
0x00010000
READ_CONTROL = 
0x20000
WRITE_DAC = 
0x40000
WRITE_OWNER = 
0x80000
OWNER_SECURITY_INFORMATION = 
1
GROUP_SECURITY_INFORMATION = 
2
DACL_SECURITY_INFORMATION = 
4
FILE_PERSISTENT_ACLS = 
0x00000008
MASK_TO_MODE = 
{
  FILE::FILE_GENERIC_READ => S_IROTH,
  FILE::FILE_GENERIC_WRITE => S_IWOTH,
  (FILE::FILE_GENERIC_EXECUTE & ~FILE::FILE_READ_ATTRIBUTES) => S_IXOTH
}
MODE_TO_MASK = 
{
  S_IROTH => FILE::FILE_GENERIC_READ,
  S_IWOTH => FILE::FILE_GENERIC_WRITE,
  S_IXOTH => (FILE::FILE_GENERIC_EXECUTE & ~FILE::FILE_READ_ATTRIBUTES),
}
ACL_REVISION = 
2
SE_PRIVILEGE_ENABLED = 
0x00000002
TOKEN_ADJUST_PRIVILEGES = 
0x0020
MAXIMUM_SID_BYTES_LENGTH =

stackoverflow.com/a/1792930

68
MAXIMUM_GENERIC_ACE_SIZE = 
GENERIC_ACCESS_ACE.offset_of(:SidStart) +
MAXIMUM_SID_BYTES_LENGTH
SE_OBJECT_TYPE =

msdn.microsoft.com/en-us/library/windows/desktop/aa379593(v=vs.85).aspx

enum(
  :SE_UNKNOWN_OBJECT_TYPE, 0,
  :SE_FILE_OBJECT,
  :SE_SERVICE,
  :SE_PRINTER,
  :SE_REGISTRY_KEY,
  :SE_LMSHARE,
  :SE_KERNEL_OBJECT,
  :SE_WINDOW_OBJECT,
  :SE_DS_OBJECT,
  :SE_DS_OBJECT_ALL,
  :SE_PROVIDER_DEFINED_OBJECT,
  :SE_WMIGUID_OBJECT,
  :SE_REGISTRY_WOW64_32KEY
)

Instance Method Summary collapse

Methods included from String

wide_string

Instance Method Details

#add_access_allowed_ace(acl, mask, sid, inherit = nil) ⇒ Object 



431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/puppet/util/windows/security.rb', line 431

def add_access_allowed_ace(acl, mask, sid, inherit = nil)
  inherit ||= NO_INHERITANCE

  Puppet::Util::Windows::SID.string_to_sid_ptr(sid) do |sid_ptr|
    if Puppet::Util::Windows::SID.IsValidSid(sid_ptr) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Invalid SID")
    end

    if AddAccessAllowedAceEx(acl, ACL_REVISION, inherit, mask, sid_ptr) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Failed to add access control entry")
    end
  end

  # ensure this method is void if it doesn't raise
  nil
end

#add_access_denied_ace(acl, mask, sid, inherit = nil) ⇒ Object 



448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
 
# File 'lib/puppet/util/windows/security.rb', line 448

def add_access_denied_ace(acl, mask, sid, inherit = nil)
  inherit ||= NO_INHERITANCE

  Puppet::Util::Windows::SID.string_to_sid_ptr(sid) do |sid_ptr|
    if Puppet::Util::Windows::SID.IsValidSid(sid_ptr) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Invalid SID")
    end

    if AddAccessDeniedAceEx(acl, ACL_REVISION, inherit, mask, sid_ptr) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Failed to add access control entry")
    end
  end

  # ensure this method is void if it doesn't raise
  nil
end

#get_aces_for_path_by_sid(path, sid) ⇒ Object 



191
192
193
 
# File 'lib/puppet/util/windows/security.rb', line 191

def get_aces_for_path_by_sid(path, sid)
  get_security_descriptor(path).dacl.select { |ace| ace.sid == sid }
end

#get_group(path) ⇒ Object

Get the group of the object referenced by path. The returned value is a SID string, e.g. “S-1-5-32-544”. Any user with read access to an object can get the group. Only a user with the SE_BACKUP_NAME privilege in their process token can get the group for objects they do not have read access to.



158
159
160
161
162
 
# File 'lib/puppet/util/windows/security.rb', line 158

def get_group(path)
  return unless supports_acl?(path)

  get_security_descriptor(path).group
end

#get_max_generic_acl_size(ace_count) ⇒ Object 



631
632
633
634
635
636
637
638
 
# File 'lib/puppet/util/windows/security.rb', line 631

def get_max_generic_acl_size(ace_count)
  # https://msdn.microsoft.com/en-us/library/windows/desktop/aa378853(v=vs.85).aspx
  # To calculate the initial size of an ACL, add the following together, and then align the result to the nearest DWORD:
  # * Size of the ACL structure.
  # * Size of each ACE structure that the ACL is to contain minus the SidStart member (DWORD) of the ACE.
  # * Length of the SID that each ACE is to contain.
  ACL.size + ace_count * MAXIMUM_GENERIC_ACE_SIZE
end

#get_mode(path) ⇒ Object

Get the mode of the object referenced by path. The returned integer value represents the POSIX-style read, write, and execute modes for the user, group, and other classes, e.g. 0640. Any user with read access to an object can get the mode. Only a user with the SE_BACKUP_NAME privilege in their process token can get the mode for objects they do not have read access to.



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/puppet/util/windows/security.rb', line 201

def get_mode(path)
  return unless supports_acl?(path)

  well_known_world_sid = Puppet::Util::Windows::SID::Everyone
  well_known_nobody_sid = Puppet::Util::Windows::SID::Nobody
  well_known_system_sid = Puppet::Util::Windows::SID::LocalSystem
  well_known_app_packages_sid = Puppet::Util::Windows::SID::AllAppPackages

  mode = S_ISYSTEM_MISSING

  sd = get_security_descriptor(path)
  sd.dacl.each do |ace|
    next if ace.inherit_only?

    case ace.sid
    when sd.owner
      MASK_TO_MODE.each_pair do |k, v|
        if (ace.mask & k) == k
          mode |= (v << 6)
        end
      end
    when sd.group
      MASK_TO_MODE.each_pair do |k, v|
        if (ace.mask & k) == k
          mode |= (v << 3)
        end
      end
    when well_known_world_sid
      MASK_TO_MODE.each_pair do |k, v|
        if (ace.mask & k) == k
          mode |= (v << 6) | (v << 3) | v
        end
      end
      if File.directory?(path) &&
         (ace.mask & (FILE::FILE_WRITE_DATA | FILE::FILE_EXECUTE | FILE::FILE_DELETE_CHILD)) == (FILE::FILE_WRITE_DATA | FILE::FILE_EXECUTE)
        mode |= S_ISVTX;
      end
    when well_known_nobody_sid
      if (ace.mask & FILE::FILE_APPEND_DATA).nonzero?
        mode |= S_ISVTX
      end
    when well_known_app_packages_sid, well_known_system_sid
      # do nothing
    else
      # puts "Warning, unable to map SID into POSIX mode: #{ace.sid}"
      mode |= S_IEXTRA
    end

    if ace.sid == well_known_system_sid
      mode &= ~S_ISYSTEM_MISSING
    end

    # if owner and group the same, then user and group modes are the OR of both
    if sd.owner == sd.group
      mode |= ((mode & S_IRWXG) << 3) | ((mode & S_IRWXU) >> 3)
      # puts "owner: #{sd.group}, 0x#{ace.mask.to_s(16)}, #{mode.to_s(8)}"
    end
  end

  # puts "get_mode: #{mode.to_s(8)}"
  mode
end

#get_owner(path) ⇒ Object

Get the owner of the object referenced by path. The returned value is a SID string, e.g. “S-1-5-32-544”. Any user with read access to an object can get the owner. Only a user with the SE_BACKUP_NAME privilege in their process token can get the owner for objects they do not have read access to.



133
134
135
136
137
 
# File 'lib/puppet/util/windows/security.rb', line 133

def get_owner(path)
  return unless supports_acl?(path)

  get_security_descriptor(path).owner
end

#get_security_descriptor(path) ⇒ Object 



583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
 
# File 'lib/puppet/util/windows/security.rb', line 583

def get_security_descriptor(path)
  sd = nil

  with_privilege(SE_BACKUP_NAME) do
    open_file(path, READ_CONTROL) do |handle|
      FFI::MemoryPointer.new(:pointer, 1) do |owner_sid_ptr_ptr|
        FFI::MemoryPointer.new(:pointer, 1) do |group_sid_ptr_ptr|
          FFI::MemoryPointer.new(:pointer, 1) do |dacl_ptr_ptr|
            FFI::MemoryPointer.new(:pointer, 1) do |sd_ptr_ptr|
              rv = GetSecurityInfo(
                handle,
                :SE_FILE_OBJECT,
                OWNER_SECURITY_INFORMATION | GROUP_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION,
                owner_sid_ptr_ptr,
                group_sid_ptr_ptr,
                dacl_ptr_ptr,
                FFI::Pointer::NULL, # sacl
                sd_ptr_ptr
              ) # sec desc
              raise Puppet::Util::Windows::Error, _("Failed to get security information") if rv != FFI::ERROR_SUCCESS

              # these 2 convenience params are not freed since they point inside sd_ptr
              owner = Puppet::Util::Windows::SID.sid_ptr_to_string(owner_sid_ptr_ptr.get_pointer(0))
              group = Puppet::Util::Windows::SID.sid_ptr_to_string(group_sid_ptr_ptr.get_pointer(0))

              FFI::MemoryPointer.new(:word, 1) do |control|
                FFI::MemoryPointer.new(:dword, 1) do |revision|
                  sd_ptr_ptr.read_win32_local_pointer do |sd_ptr|
                    if GetSecurityDescriptorControl(sd_ptr, control, revision) == FFI::WIN32_FALSE
                      raise Puppet::Util::Windows::Error, _("Failed to get security descriptor control")
                    end

                    protect = (control.read_word & SE_DACL_PROTECTED) == SE_DACL_PROTECTED
                    dacl = parse_dacl(dacl_ptr_ptr.get_pointer(0))
                    sd = Puppet::Util::Windows::SecurityDescriptor.new(owner, group, dacl, protect)
                  end
                end
              end
            end
          end
        end
      end
    end
  end

  sd
end

#open_file(path, access, &block) ⇒ Object

Open an existing file with the specified access mode, and execute a block with the opened file HANDLE.



513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
 
# File 'lib/puppet/util/windows/security.rb', line 513

def open_file(path, access, &block)
  handle = CreateFileW(
    wide_string(path),
    access,
    FILE::FILE_SHARE_READ | FILE::FILE_SHARE_WRITE,
    FFI::Pointer::NULL, # security_attributes
    FILE::OPEN_EXISTING,
    FILE::FILE_FLAG_OPEN_REPARSE_POINT | FILE::FILE_FLAG_BACKUP_SEMANTICS,
    FFI::Pointer::NULL_HANDLE
  ) # template

  if handle == Puppet::Util::Windows::File::INVALID_HANDLE_VALUE
    raise Puppet::Util::Windows::Error, _("Failed to open '%{path}'") % { path: path }
  end

  begin
    yield handle
  ensure
    FFI::WIN32.CloseHandle(handle) if handle
  end

  # handle has already had CloseHandle called against it, nothing to return
  nil
end

#parse_dacl(dacl_ptr) ⇒ Object 



465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
 
# File 'lib/puppet/util/windows/security.rb', line 465

def parse_dacl(dacl_ptr)
  # REMIND: need to handle NULL DACL
  if IsValidAcl(dacl_ptr) == FFI::WIN32_FALSE
    raise Puppet::Util::Windows::Error, _("Invalid DACL")
  end

  dacl_struct = ACL.new(dacl_ptr)
  ace_count = dacl_struct[:AceCount]

  dacl = Puppet::Util::Windows::AccessControlList.new

  # deny all
  return dacl if ace_count == 0

  0.upto(ace_count - 1) do |i|
    FFI::MemoryPointer.new(:pointer, 1) do |ace_ptr|
      next if GetAce(dacl_ptr, i, ace_ptr) == FFI::WIN32_FALSE

      # ACE structures vary depending on the type. We are only concerned with
      # ACCESS_ALLOWED_ACE and ACCESS_DENIED_ACEs, which have the same layout
      ace = GENERIC_ACCESS_ACE.new(ace_ptr.get_pointer(0)) # deref LPVOID *

      ace_type = ace[:Header][:AceType]
      if ace_type != Puppet::Util::Windows::AccessControlEntry::ACCESS_ALLOWED_ACE_TYPE &&
         ace_type != Puppet::Util::Windows::AccessControlEntry::ACCESS_DENIED_ACE_TYPE
        Puppet.warning _("Unsupported access control entry type: 0x%{type}") % { type: ace_type.to_s(16) }
        next
      end

      # using pointer addition gives the FFI::Pointer a size, but that's OK here
      sid = Puppet::Util::Windows::SID.sid_ptr_to_string(ace.pointer + GENERIC_ACCESS_ACE.offset_of(:SidStart))
      mask = ace[:Mask]
      ace_flags = ace[:Header][:AceFlags]

      case ace_type
      when Puppet::Util::Windows::AccessControlEntry::ACCESS_ALLOWED_ACE_TYPE
        dacl.allow(sid, mask, ace_flags)
      when Puppet::Util::Windows::AccessControlEntry::ACCESS_DENIED_ACE_TYPE
        dacl.deny(sid, mask, ace_flags)
      end
    end
  end

  dacl
end

#set_group(group_sid, path) ⇒ Object

Set the owner of the object referenced by path to the specified group_sid. The group sid should be of the form “S-1-5-32-544” and can either be a user or group. Any user with WRITE_OWNER access to the object can change the group (regardless of whether the current user belongs to that group or not).



144
145
146
147
148
149
150
151
 
# File 'lib/puppet/util/windows/security.rb', line 144

def set_group(group_sid, path)
  sd = get_security_descriptor(path)

  if group_sid != sd.group
    sd.group = group_sid
    set_security_descriptor(path, sd)
  end
end

#set_mode(mode, path, protected = true, managing_owner = false, managing_group = false) ⇒ Object

Set the mode of the object referenced by path to the specified mode. The mode should be specified as POSIX-style read, write, and execute modes for the user, group, and other classes, e.g. 0640. The sticky bit, S_ISVTX, is supported, but is only meaningful for directories. If set, group and others are not allowed to delete child objects for which they are not the owner. By default, the DACL is set to protected, meaning it does not inherit access control entries from parent objects. This can be changed by setting protected to false. The owner of the object (with READ_CONTROL and WRITE_DACL access) can always change the mode. Only a user with the SE_BACKUP_NAME and SE_RESTORE_NAME privileges in their process token can change the mode for objects that they do not have read and write access to.



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/puppet/util/windows/security.rb', line 283

def set_mode(mode, path, protected = true, managing_owner = false, managing_group = false)
  sd = get_security_descriptor(path)
  well_known_world_sid = Puppet::Util::Windows::SID::Everyone
  well_known_nobody_sid = Puppet::Util::Windows::SID::Nobody
  well_known_system_sid = Puppet::Util::Windows::SID::LocalSystem

  owner_allow = FILE::STANDARD_RIGHTS_ALL  |
                FILE::FILE_READ_ATTRIBUTES |
                FILE::FILE_WRITE_ATTRIBUTES
  # this prevents a mode that is not 7 from taking ownership of a file based
  # on group membership and rewriting it / making it executable
  group_allow = FILE::STANDARD_RIGHTS_READ |
                FILE::FILE_READ_ATTRIBUTES |
                FILE::SYNCHRONIZE
  other_allow = FILE::STANDARD_RIGHTS_READ |
                FILE::FILE_READ_ATTRIBUTES |
                FILE::SYNCHRONIZE
  nobody_allow = 0
  system_allow = 0

  MODE_TO_MASK.each do |k, v|
    if ((mode >> 6) & k) == k
      owner_allow |= v
    end
    if ((mode >> 3) & k) == k
      group_allow |= v
    end
    if (mode & k) == k
      other_allow |= v
    end
  end

  # With a mode value of '7' for group / other, the value must then include
  # additional perms beyond STANDARD_RIGHTS_READ to allow DACL modification
  if (mode & S_IRWXG) == S_IRWXG
    group_allow |= FILE::DELETE | FILE::WRITE_DAC | FILE::WRITE_OWNER
  end
  if (mode & S_IRWXO) == S_IRWXO
    other_allow |= FILE::DELETE | FILE::WRITE_DAC | FILE::WRITE_OWNER
  end

  if (mode & S_ISVTX).nonzero?
    nobody_allow |= FILE::FILE_APPEND_DATA;
  end

  isownergroup = sd.owner == sd.group

  # caller is NOT managing SYSTEM by using group or owner, so set to FULL
  if ![sd.owner, sd.group].include? well_known_system_sid
    # we don't check S_ISYSTEM_MISSING bit, but automatically carry over existing SYSTEM perms
    # by default set SYSTEM perms to full
    system_allow = FILE::FILE_ALL_ACCESS
  else
    # It is possible to set SYSTEM with a mode other than Full Control (7) however this makes no sense and in practical terms
    # should not be done.  We can trap these instances and correct them before being applied.
    if (sd.owner == well_known_system_sid) && (owner_allow != FILE::FILE_ALL_ACCESS)
      # If owner and group are both SYSTEM but group is unmanaged the control rights of system will be set to FullControl by
      # the unmanaged group, so there is no need for the warning
      if managing_owner && (!isownergroup || managing_group)
        # TRANSLATORS 'SYSTEM' is a Windows name and should not be translated
        Puppet.warning _("Setting control rights for %{path} owner SYSTEM to less than Full Control rights. Setting SYSTEM rights to less than Full Control may have unintented consequences for operations on this file") % { path: path }
      elsif managing_owner && isownergroup
        # TRANSLATORS 'SYSTEM' is a Windows name and should not be translated
        Puppet.debug { _("%{path} owner and group both set to user SYSTEM, but group is not managed directly: SYSTEM user rights will be set to FullControl by group") % { path: path } }
      else
        # TRANSLATORS 'SYSTEM' is a Windows name and should not be translated
        Puppet.debug { _("An attempt to set mode %{mode} on item %{path} would result in the owner, SYSTEM, to have less than Full Control rights. This attempt has been corrected to Full Control") % { mode: mode.to_s(8), path: path } }
        owner_allow = FILE::FILE_ALL_ACCESS
      end
    end

    if (sd.group == well_known_system_sid) && (group_allow != FILE::FILE_ALL_ACCESS)
      # If owner and group are both SYSTEM but owner is unmanaged the control rights of system will be set to FullControl by
      # the unmanaged owner, so there is no need for the warning.
      if managing_group && (!isownergroup || managing_owner)
        # TRANSLATORS 'SYSTEM' is a Windows name and should not be translated
        Puppet.warning _("Setting control rights for %{path} group SYSTEM to less than Full Control rights. Setting SYSTEM rights to less than Full Control may have unintented consequences for operations on this file") % { path: path }
      elsif managing_group && isownergroup
        # TRANSLATORS 'SYSTEM' is a Windows name and should not be translated
        Puppet.debug { _("%{path} owner and group both set to user SYSTEM, but owner is not managed directly: SYSTEM user rights will be set to FullControl by owner") % { path: path } }
      else
        # TRANSLATORS 'SYSTEM' is a Windows name and should not be translated
        Puppet.debug { _("An attempt to set mode %{mode} on item %{path} would result in the group, SYSTEM, to have less than Full Control rights. This attempt has been corrected to Full Control") % { mode: mode.to_s(8), path: path } }
        group_allow = FILE::FILE_ALL_ACCESS
      end
    end
  end

  # even though FILE_DELETE_CHILD only applies to directories, it can be set on files
  # this is necessary to do to ensure a file ends up with (F) FullControl
  if (mode & (S_IWUSR | S_IXUSR)) == (S_IWUSR | S_IXUSR)
    owner_allow |= FILE::FILE_DELETE_CHILD
  end
  if (mode & (S_IWGRP | S_IXGRP)) == (S_IWGRP | S_IXGRP) && (mode & S_ISVTX) == 0
    group_allow |= FILE::FILE_DELETE_CHILD
  end
  if (mode & (S_IWOTH | S_IXOTH)) == (S_IWOTH | S_IXOTH) && (mode & S_ISVTX) == 0
    other_allow |= FILE::FILE_DELETE_CHILD
  end

  # if owner and group the same, then map group permissions to the one owner ACE
  if isownergroup
    owner_allow |= group_allow
  end

  # if any ACE allows write, then clear readonly bit, but do this before we overwrite
  # the DACl and lose our ability to set the attribute
  if ((owner_allow | group_allow | other_allow) & FILE::FILE_WRITE_DATA) == FILE::FILE_WRITE_DATA
    FILE.remove_attributes(path, FILE::FILE_ATTRIBUTE_READONLY)
  end

  isdir = File.directory?(path)
  dacl = Puppet::Util::Windows::AccessControlList.new
  dacl.allow(sd.owner, owner_allow)
  unless isownergroup
    dacl.allow(sd.group, group_allow)
  end
  dacl.allow(well_known_world_sid, other_allow)
  dacl.allow(well_known_nobody_sid, nobody_allow)

  # TODO: system should be first?
  flags = !isdir ? 0 :
    Puppet::Util::Windows::AccessControlEntry::CONTAINER_INHERIT_ACE |
      Puppet::Util::Windows::AccessControlEntry::OBJECT_INHERIT_ACE
  dacl.allow(well_known_system_sid, system_allow, flags)

  # add inherit-only aces for child dirs and files that are created within the dir
  inherit_only = Puppet::Util::Windows::AccessControlEntry::INHERIT_ONLY_ACE
  if isdir
    inherit = inherit_only | Puppet::Util::Windows::AccessControlEntry::CONTAINER_INHERIT_ACE
    dacl.allow(Puppet::Util::Windows::SID::CreatorOwner, owner_allow, inherit)
    dacl.allow(Puppet::Util::Windows::SID::CreatorGroup, group_allow, inherit)

    inherit = inherit_only | Puppet::Util::Windows::AccessControlEntry::OBJECT_INHERIT_ACE
    # allow any previously set bits *except* for these
    perms_to_strip = ~(FILE::FILE_EXECUTE + FILE::WRITE_OWNER + FILE::WRITE_DAC)
    dacl.allow(Puppet::Util::Windows::SID::CreatorOwner, owner_allow & perms_to_strip, inherit)
    dacl.allow(Puppet::Util::Windows::SID::CreatorGroup, group_allow & perms_to_strip, inherit)
  end

  new_sd = Puppet::Util::Windows::SecurityDescriptor.new(sd.owner, sd.group, dacl, protected)
  set_security_descriptor(path, new_sd)

  nil
end

#set_owner(owner_sid, path) ⇒ Object

Set the owner of the object referenced by path to the specified owner_sid. The owner sid should be of the form “S-1-5-32-544” and can either be a user or group. Only a user with the SE_RESTORE_NAME privilege in their process token can overwrite the object’s owner to something other than the current user.



119
120
121
122
123
124
125
126
 
# File 'lib/puppet/util/windows/security.rb', line 119

def set_owner(owner_sid, path)
  sd = get_security_descriptor(path)

  if owner_sid != sd.owner
    sd.owner = owner_sid
    set_security_descriptor(path, sd)
  end
end

#set_privilege(privilege, enable) ⇒ Object

Enable or disable a privilege. Note this doesn’t add any privileges the user doesn’t already has, it just enables privileges that are disabled.



551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
 
# File 'lib/puppet/util/windows/security.rb', line 551

def set_privilege(privilege, enable)
  return unless Puppet.features.root?

  Puppet::Util::Windows::Process.with_process_token(TOKEN_ADJUST_PRIVILEGES) do |token|
    Puppet::Util::Windows::Process.lookup_privilege_value(privilege) do |luid|
      FFI::MemoryPointer.new(Puppet::Util::Windows::Process::LUID_AND_ATTRIBUTES.size) do |luid_and_attributes_ptr|
        # allocate unmanaged memory for structs that we clean up afterwards
        luid_and_attributes = Puppet::Util::Windows::Process::LUID_AND_ATTRIBUTES.new(luid_and_attributes_ptr)
        luid_and_attributes[:Luid] = luid
        luid_and_attributes[:Attributes] = enable ? SE_PRIVILEGE_ENABLED : 0

        FFI::MemoryPointer.new(Puppet::Util::Windows::Process::TOKEN_PRIVILEGES.size) do |token_privileges_ptr|
          token_privileges = Puppet::Util::Windows::Process::TOKEN_PRIVILEGES.new(token_privileges_ptr)
          token_privileges[:PrivilegeCount] = 1
          token_privileges[:Privileges][0] = luid_and_attributes

          # size is correct given we only have 1 LUID, otherwise would be:
          # [:PrivilegeCount].size + [:PrivilegeCount] * LUID_AND_ATTRIBUTES.size
          if AdjustTokenPrivileges(token, FFI::WIN32_FALSE,
                                   token_privileges, token_privileges.size,
                                   FFI::MemoryPointer::NULL, FFI::MemoryPointer::NULL) == FFI::WIN32_FALSE
            raise Puppet::Util::Windows::Error, _("Failed to adjust process privileges")
          end
        end
      end
    end
  end

  # token / luid structs freed by this point, so return true as nothing raised
  true
end

#set_security_descriptor(path, sd) ⇒ Object

setting DACL requires both READ_CONTROL and WRITE_DACL access rights, and their respective privileges, SE_BACKUP_NAME and SE_RESTORE_NAME.



642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
 
# File 'lib/puppet/util/windows/security.rb', line 642

def set_security_descriptor(path, sd)
  FFI::MemoryPointer.new(:byte, get_max_generic_acl_size(sd.dacl.count)) do |acl_ptr|
    if InitializeAcl(acl_ptr, acl_ptr.size, ACL_REVISION) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Failed to initialize ACL")
    end

    if IsValidAcl(acl_ptr) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Invalid DACL")
    end

    with_privilege(SE_BACKUP_NAME) do
      with_privilege(SE_RESTORE_NAME) do
        open_file(path, READ_CONTROL | WRITE_DAC | WRITE_OWNER) do |handle|
          Puppet::Util::Windows::SID.string_to_sid_ptr(sd.owner) do |owner_sid_ptr|
            Puppet::Util::Windows::SID.string_to_sid_ptr(sd.group) do |group_sid_ptr|
              sd.dacl.each do |ace|
                case ace.type
                when Puppet::Util::Windows::AccessControlEntry::ACCESS_ALLOWED_ACE_TYPE
                  # puts "ace: allow, sid #{Puppet::Util::Windows::SID.sid_to_name(ace.sid)}, mask 0x#{ace.mask.to_s(16)}"
                  add_access_allowed_ace(acl_ptr, ace.mask, ace.sid, ace.flags)
                when Puppet::Util::Windows::AccessControlEntry::ACCESS_DENIED_ACE_TYPE
                  # puts "ace: deny, sid #{Puppet::Util::Windows::SID.sid_to_name(ace.sid)}, mask 0x#{ace.mask.to_s(16)}"
                  add_access_denied_ace(acl_ptr, ace.mask, ace.sid, ace.flags)
                else
                  raise "We should never get here"
                  # TODO: this should have been a warning in an earlier commit
                end
              end

              # protected means the object does not inherit aces from its parent
              flags = OWNER_SECURITY_INFORMATION | GROUP_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION
              flags |= sd.protect ? PROTECTED_DACL_SECURITY_INFORMATION : UNPROTECTED_DACL_SECURITY_INFORMATION

              rv = SetSecurityInfo(handle,
                                   :SE_FILE_OBJECT,
                                   flags,
                                   owner_sid_ptr,
                                   group_sid_ptr,
                                   acl_ptr,
                                   FFI::MemoryPointer::NULL)

              if rv != FFI::ERROR_SUCCESS
                raise Puppet::Util::Windows::Error, _("Failed to set security information")
              end
            end
          end
        end
      end
    end
  end
end

#supports_acl?(path) ⇒ Boolean

Returns:

  • (Boolean) 


166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/puppet/util/windows/security.rb', line 166

def supports_acl?(path)
  supported = false
  root = Pathname.new(path).enum_for(:ascend).to_a.last.to_s
  # 'A trailing backslash is required'
  root = "#{root}\\" unless root =~ %r{[/\\]$}

  FFI::MemoryPointer.new(:pointer, 1) do |flags_ptr|
    if GetVolumeInformationW(wide_string(root), FFI::Pointer::NULL, 0,
                             FFI::Pointer::NULL, FFI::Pointer::NULL,
                             flags_ptr, FFI::Pointer::NULL, 0) == FFI::WIN32_FALSE
      raise Puppet::Util::Windows::Error, _("Failed to get volume information")
    end

    supported = flags_ptr.read_dword & FILE_PERSISTENT_ACLS == FILE_PERSISTENT_ACLS
  end

  supported
end

#with_privilege(privilege, &block) ⇒ Object

Execute a block with the specified privilege enabled



539
540
541
542
543
544
 
# File 'lib/puppet/util/windows/security.rb', line 539

def with_privilege(privilege, &block)
  set_privilege(privilege, true)
  yield
ensure
  set_privilege(privilege, false)
end