Class: Win32::Security::ACL

Inherits:
Object
  • Object
show all
Extended by:
Windows::Security::Functions
Includes:
Windows::Security::Constants, Windows::Security::Functions, Windows::Security::Structs
Defined in:
lib/win32/security/acl.rb

Overview

The ACL class encapsulates an Access Control List.

Constant Summary collapse

VERSION =

The version of the Win32::Security::ACL class.

'0.2.0'

Constants included from Windows::Security::Constants

Windows::Security::Constants::ACL_REVISION, Windows::Security::Constants::ACL_REVISION1, Windows::Security::Constants::ACL_REVISION2, Windows::Security::Constants::ACL_REVISION3, Windows::Security::Constants::ACL_REVISION4, Windows::Security::Constants::AclRevisionInformation, Windows::Security::Constants::AclSizeInformation, Windows::Security::Constants::DOMAIN_ALIAS_RID_ACCOUNT_OPS, Windows::Security::Constants::DOMAIN_ALIAS_RID_ADMINS, Windows::Security::Constants::DOMAIN_ALIAS_RID_AUTHORIZATIONACCESS, Windows::Security::Constants::DOMAIN_ALIAS_RID_BACKUP_OPS, Windows::Security::Constants::DOMAIN_ALIAS_RID_DCOM_USERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_GUESTS, Windows::Security::Constants::DOMAIN_ALIAS_RID_INCOMING_FOREST_TRUST_BUILDERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_LOGGING_USERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_MONITORING_USERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_NETWORK_CONFIGURATION_OPS, Windows::Security::Constants::DOMAIN_ALIAS_RID_POWER_USERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_PREW2KCOMPACCESS, Windows::Security::Constants::DOMAIN_ALIAS_RID_PRINT_OPS, Windows::Security::Constants::DOMAIN_ALIAS_RID_RAS_SERVERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_REMOTE_DESKTOP_USERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_REPLICATOR, Windows::Security::Constants::DOMAIN_ALIAS_RID_SYSTEM_OPS, Windows::Security::Constants::DOMAIN_ALIAS_RID_TS_LICENSE_SERVERS, Windows::Security::Constants::DOMAIN_ALIAS_RID_USERS, Windows::Security::Constants::DOMAIN_GROUP_RID_ADMINS, Windows::Security::Constants::DOMAIN_GROUP_RID_CERT_ADMINS, Windows::Security::Constants::DOMAIN_GROUP_RID_COMPUTERS, Windows::Security::Constants::DOMAIN_GROUP_RID_CONTROLLERS, Windows::Security::Constants::DOMAIN_GROUP_RID_ENTERPRISE_ADMINS, Windows::Security::Constants::DOMAIN_GROUP_RID_GUESTS, Windows::Security::Constants::DOMAIN_GROUP_RID_POLICY_ADMINS, Windows::Security::Constants::DOMAIN_GROUP_RID_SCHEMA_ADMINS, Windows::Security::Constants::DOMAIN_GROUP_RID_USERS, Windows::Security::Constants::DOMAIN_USER_RID_ADMIN, Windows::Security::Constants::DOMAIN_USER_RID_GUEST, Windows::Security::Constants::DOMAIN_USER_RID_KRBTGT, Windows::Security::Constants::DOMAIN_USER_RID_MAX, Windows::Security::Constants::ERROR_NO_TOKEN, Windows::Security::Constants::FOREST_USER_RID_MAX, Windows::Security::Constants::SECURITY_ANONYMOUS_LOGON_RID, Windows::Security::Constants::SECURITY_AUTHENTICATED_USER_RID, Windows::Security::Constants::SECURITY_BATCH_RID, Windows::Security::Constants::SECURITY_BUILTIN_DOMAIN_RID, Windows::Security::Constants::SECURITY_CREATOR_GROUP_RID, Windows::Security::Constants::SECURITY_CREATOR_GROUP_SERVER_RID, Windows::Security::Constants::SECURITY_CREATOR_OWNER_RID, Windows::Security::Constants::SECURITY_CREATOR_OWNER_SERVER_RID, Windows::Security::Constants::SECURITY_CREATOR_SID_AUTHORITY, Windows::Security::Constants::SECURITY_DIALUP_RID, Windows::Security::Constants::SECURITY_ENTERPRISE_CONTROLLERS_RID, Windows::Security::Constants::SECURITY_INTERACTIVE_RID, Windows::Security::Constants::SECURITY_LOCAL_RID, Windows::Security::Constants::SECURITY_LOCAL_SERVICE_RID, Windows::Security::Constants::SECURITY_LOCAL_SID_AUTHORITY, Windows::Security::Constants::SECURITY_LOCAL_SYSTEM_RID, Windows::Security::Constants::SECURITY_LOGON_IDS_RID, Windows::Security::Constants::SECURITY_LOGON_IDS_RID_COUNT, Windows::Security::Constants::SECURITY_MAX_ALWAYS_FILTERED, Windows::Security::Constants::SECURITY_MIN_NEVER_FILTERED, Windows::Security::Constants::SECURITY_NETWORK_RID, Windows::Security::Constants::SECURITY_NETWORK_SERVICE_RID, Windows::Security::Constants::SECURITY_NON_UNIQUE_AUTHORITY, Windows::Security::Constants::SECURITY_NT_AUTHORITY, Windows::Security::Constants::SECURITY_NT_NON_UNIQUE, Windows::Security::Constants::SECURITY_NT_NON_UNIQUE_SUB_AUTH_COUNT, Windows::Security::Constants::SECURITY_NULL_RID, Windows::Security::Constants::SECURITY_NULL_SID_AUTHORITY, Windows::Security::Constants::SECURITY_OTHER_ORGANIZATION_RID, Windows::Security::Constants::SECURITY_PACKAGE_BASE_RID, Windows::Security::Constants::SECURITY_PACKAGE_DIGEST_RID, Windows::Security::Constants::SECURITY_PACKAGE_NTLM_RID, Windows::Security::Constants::SECURITY_PACKAGE_RID_COUNT, Windows::Security::Constants::SECURITY_PACKAGE_SCHANNEL_RID, Windows::Security::Constants::SECURITY_PRINCIPAL_SELF_RID, Windows::Security::Constants::SECURITY_PROXY_RID, Windows::Security::Constants::SECURITY_REMOTE_LOGON_RID, Windows::Security::Constants::SECURITY_RESOURCE_MANAGER_AUTHORITY, Windows::Security::Constants::SECURITY_RESTRICTED_CODE_RID, Windows::Security::Constants::SECURITY_SERVER_LOGON_RID, Windows::Security::Constants::SECURITY_SERVICE_RID, Windows::Security::Constants::SECURITY_TERMINAL_SERVER_RID, Windows::Security::Constants::SECURITY_THIS_ORGANIZATION_RID, Windows::Security::Constants::SECURITY_WORLD_RID, Windows::Security::Constants::SECURITY_WORLD_SID_AUTHORITY, Windows::Security::Constants::SidTypeAlias, Windows::Security::Constants::SidTypeComputer, Windows::Security::Constants::SidTypeDeletedAccount, Windows::Security::Constants::SidTypeDomain, Windows::Security::Constants::SidTypeGroup, Windows::Security::Constants::SidTypeInvalid, Windows::Security::Constants::SidTypeUnknown, Windows::Security::Constants::SidTypeUser, Windows::Security::Constants::SidTypeWellKnownGroup, Windows::Security::Constants::TOKEN_QUERY

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(revision = ACL_REVISION) ⇒ ACL

Creates and returns a new Win32::Security::ACL object. This object encapsulates an ACL structure, including a binary representation of the ACL itself, and the revision information.



31
32
33
34
35
36
37
38
39
40
 
# File 'lib/win32/security/acl.rb', line 31

def initialize(revision = ACL_REVISION)
  acl = ACL_STRUCT.new

  unless InitializeAcl(acl, acl.size, revision)
    raise SystemCallError.new("InitializeAcl", FFI.errno)
  end

  @acl = acl
  @revision = revision
end

Instance Attribute Details

#acl ⇒ Object (readonly)

The underlying ACL structure.



22
23
24
 
# File 'lib/win32/security/acl.rb', line 22

def acl
  @acl
end

#revision ⇒ Object

The revision level.



25
26
27
 
# File 'lib/win32/security/acl.rb', line 25

def revision
  @revision
end

Instance Method Details

#ace_count ⇒ Object

Returns the number of ACE’s in the ACL object.



44
45
46
47
48
49
50
51
52
 
# File 'lib/win32/security/acl.rb', line 44

def ace_count
  info = ACL_SIZE_INFORMATION.new

  unless GetAclInformation(@acl, info, info.size, AclSizeInformation)
    raise SystemCallError.new("GetAclInformation", FFI.errno)
  end

  info[:AceCount]
end

#add_access_allowed_ace(sid, mask = 0) ⇒ Object

Adds an access allowed ACE to the given sid. The mask is a bitwise OR’d value of access rights.

TODO: Move this into the SID class?



58
59
60
61
62
 
# File 'lib/win32/security/acl.rb', line 58

def add_access_allowed_ace(sid, mask=0)
  unless AddAccessAllowedAce(@acl, @revision, mask, sid)
    raise SystemCallError.new("AddAccessAllowedAce", FFI.errno)
  end
end

#add_access_denied_ace(sid, mask = 0) ⇒ Object

Adds an access denied ACE to the given sid.



66
67
68
69
70
 
# File 'lib/win32/security/acl.rb', line 66

def add_access_denied_ace(sid, mask=0)
  unless AddAccessDeniedAce(@acl, @revision, mask, sid)
    raise SystemCallError.new("AddAccessDeniedAce", FFI.errno)
  end
end

#add_ace(ace, index = MAXDWORD) ⇒ Object

Adds an ACE to the ACL object with the given revision at index or the end of the chain if no index is specified.

Returns the index if successful. – This is untested and will require an actual implementation of Win32::Security::Ace before it can work properly.



80
81
82
83
84
85
86
 
# File 'lib/win32/security/acl.rb', line 80

def add_ace(ace, index=MAXDWORD)
  unless AddAce(@acl, @revision, index, ace, ace.length)
    raise SystemCallError.new("AddAce", FFI.errno)
  end

  index
end

#delete_ace(index = MAXDWORD) ⇒ Object

Deletes an ACE from the ACL object at index, or from the end of the chain if no index is specified.

Returns the index if successful. – This is untested and will require an actual implementation of Win32::Security::Ace before it can work properly.



96
97
98
99
100
101
102
 
# File 'lib/win32/security/acl.rb', line 96

def delete_ace(index=MAXDWORD)
  unless DeleteAce(@ace, index)
    raise SystemCallError.new("DeleteAce", FFI.errno)
  end

  index
end

#find_ace(index = nil) ⇒ Object

Finds and returns a pointer (address) to an ACE in the ACL at the given index. If no index is provided, then an address to the first free byte of the ACL is returned.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/win32/security/acl.rb', line 108

def find_ace(index = nil)
  pptr = FFI::MemoryPointer.new(:pointer)

  if index.nil?
    unless FindFirstFreeAce(@acl, pptr)
      raise SystemCallError.new("DeleteAce", FFI.errno)
    end
  else
    unless GetAce(@acl, index, pptr)
      raise SystemCallError.new("GetAce", FFI.errno)
    end
  end

  pptr.read_pointer.address
end

#valid? ⇒ Boolean

Returns whether or not the ACL is a valid ACL.

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/win32/security/acl.rb', line 144

def valid?
  IsValidAcl(@acl)
end