win32-security 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55e26f7dee9565c7f2bbcb65430d048ee8fde06e
-  data.tar.gz: f56540e1e2536ad249d493f772b12ff132797cec
+  metadata.gz: a1ab1418254e685f2d1fb9ab37e728f190d55084
+  data.tar.gz: c4264cb93ef3630c6234682b47f311e7853368cb
 SHA512:
-  metadata.gz: 7c2956d92cbcce0951f7b67150bdd324754e42c8faac2d5e2068e25d2bada7d12588c44775bb1c6d427415f0965f8792473a7c98c0ff57925b1f2861e0b2b605
-  data.tar.gz: e9676d488e07a8648b5e19227e5a396bb815b1377740044ac68e479bfc2489019a5fcf818ece2f63f70a4afd03788b820973c4d292d65975f83c8ff9a03ab193
+  metadata.gz: e24cc326c44285834c0c743415e4a5b3510600a5af79a5556bdc859d88e46110e4e1cd78826883e993aa343005c86ef0c1c9ac385a82d722e9290816f0a80e70
+  data.tar.gz: a39286489abc37813946ccedb911f19d02cceb149923f938a4b522042742241b476695cf89cbdcfd020d910b14951852e4433468e487ebbe16ff19c58d3ffaf0

data/CHANGES

@@ -1,3 +1,10 @@
+== 0.3.0 - 31-Oct-2014
+* Implemented an ACL class that lets you create and inspect acccess
+  control lists.
+* Implemented a basic ACE class that encapsulates an ACE object.
+* Removed Windows XP support.
+* Some minor updates to the Rakefile and gemspec.
+
 == 0.2.5 - 24-Feb-2014
 * Fixed a bug in the SID#string_to_sid method. Thanks go to Rob Reynolds
   for the spot.

data/MANIFEST

@@ -1,9 +1,9 @@
-* CHANGES
-* MANIFEST
-* README
-* Rakefile
-* win32-security.gemspec
-* lib/win32/security.rb
-* lib/win32/security/sid.rb
-* test/test_security.rb
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* win32-security.gemspec
+* lib/win32/security.rb
+* lib/win32/security/sid.rb
+* test/test_security.rb
 * test/test_sid.rb

data/README

@@ -1,6 +1,7 @@
 = Description
   A security library for MS Windows that allows you to open existing or
-  create new security identifiers (SID's).
+  create new security identifiers (SID's), as well as create access
+  control lists (ACL's).
 
 = Synopsis
   require 'win32/security'
@@ -12,15 +13,28 @@
   sid.to_s   # => "S-1-5-21-3733855671-1102023144-2002619019-1000"
   sid.length # => 28
   sid.sid    # => "\001\005\000\000\000\000\000\005\025\000\000\000..."
+
+  acl = Security::ACL.new
+  mask = Security::ACL::GENERIC_READ | Security::ACL::GENERIC_WRITE
+
+  acl.add_access_allowed_ace('some_user', mask)
+  acl.add_access_denied_ace('some_user', Security::ACL::GENERIC_EXECUTE)
+
+  acl.acl_count # => 2
+  acl.valid?    # => true
    
 == Future Plans
-  Create classes that encapsulate ACL's, ACE's, Token's, etc.
+  Create classes that encapsulate ACE's and Tokens.
    
-  There are some unfinished versions of the ACL and ACE classes in the
-  repo if you're interested in taking a look.
+  There is an unfinished versions of the ACE class in the repo if you're
+  interested in taking a look.
    
 == Known Issues
-  None that I'm aware of. Please file any bug reports on the project page at:
+  There appears to be an issue with 64-bit versions of JRuby. I believe this
+  is related to this issue: https://github.com/jruby/jruby/issues/1315. There
+  is nothing I can do about it here.
+
+  Please file any other bug reports on the project page at:
 
   https://github.com/djberg96/win32-security
 

data/Rakefile

@@ -9,7 +9,7 @@ namespace :gem do
   desc "Create the win32-security gem"
   task :create => [:clean] do
     spec = eval(IO.read('win32-security.gemspec'))
-    if Gem::VERSION < "2.0.0"
+    if Gem::VERSION < "2.0"
       Gem::Builder.new(spec).build
     else
       require 'rubygems/package'
@@ -21,7 +21,7 @@ namespace :gem do
   task :install => [:create] do
     ruby 'win32-security.gemspec'
     file = Dir["*.gem"].first
-    sh "gem install #{file}"
+    sh "gem install -l #{file}"
   end
 end
 
@@ -38,6 +38,12 @@ namespace :test do
     t.test_files = Dir['test/test_acl.rb']
   end
 
+  Rake::TestTask.new(:ace) do |t|
+    t.verbose = true
+    t.warning = true
+    t.test_files = Dir['test/test_ace.rb']
+  end
+
   Rake::TestTask.new(:sid) do |t|
     t.verbose = true
     t.warning = true

data/lib/win32/security.rb

@@ -1,9 +1,9 @@
 # This file allows users to require all security related classes from
 # a single file, instead of having to require individual files.
 
-require File.join(File.dirname(__FILE__), 'security', 'windows', 'constants')
-require File.join(File.dirname(__FILE__), 'security', 'windows', 'structs')
-require File.join(File.dirname(__FILE__), 'security', 'windows', 'functions')
+require_relative 'security/windows/constants'
+require_relative 'security/windows/structs'
+require_relative 'security/windows/functions'
 
 # The Win32 module serves as a namespace only.
 module Win32
@@ -20,7 +20,7 @@ module Win32
     extend Windows::Security::Functions
 
     # The version of the win32-security library
-    VERSION = '0.2.5'
+    VERSION = '0.3.0'
 
     # Used by OpenProcessToken
     TOKEN_QUERY = 8
@@ -33,35 +33,9 @@ module Win32
     # group.
     #
     def self.elevated_security?
-      if windows_version < 6
-        sid_ptr     = FFI::MemoryPointer.new(:pointer)
-        nt_auth_ptr = FFI::MemoryPointer.new(SID_IDENTIFIER_AUTHORITY,1)
-
-        nt_auth = SID_IDENTIFIER_AUTHORITY.new(nt_auth_ptr)
-        nt_auth[:Value].to_ptr.put_bytes(0, 0.chr*5 + 5.chr)
-
-        bool = AllocateAndInitializeSid(
-          nt_auth_ptr,
-          2,
-          SECURITY_BUILTIN_DOMAIN_RID,
-          DOMAIN_ALIAS_RID_ADMINS,
-          0, 0, 0, 0, 0, 0,
-          sid_ptr
-        )
-        unless bool
-          raise SystemCallError.new("AllocateAndInitializeSid", FFI.errno)
-        end
-
-        pbool = FFI::MemoryPointer.new(:long)
-
-        unless CheckTokenMembership(0, sid_ptr.read_pointer, pbool)
-          raise SystemCallError.new("CheckTokenMembership", FFI.errno)
-        end
-
-        pbool.read_long != 0
-      else
-        token = FFI::MemoryPointer.new(:uintptr_t)
+      result = false
 
+      FFI::MemoryPointer.new(:uintptr_t) do |token|
         unless OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, token)
           raise SystemCallError.new("OpenProcessToken", FFI.errno)
         end
@@ -82,12 +56,16 @@ module Win32
           )
 
           raise SystemCallError.new("GetTokenInformation", FFI.errno) unless bool
+
+          result = te.read_ulong != 0
         ensure
           CloseHandle(token)
+          te.free
+          rl.free
         end
-
-        te.read_ulong != 0
       end
+
+      result
     end
 
     private
@@ -107,4 +85,4 @@ end
 
 require 'win32/security/sid'
 require 'win32/security/acl'
-#require 'win32/security/ace'
+require 'win32/security/ace'

data/lib/win32/security/ace.rb

@@ -1,39 +1,75 @@
 # The Win32 module serves as a namespace only.
 module Win32
-   
+
   # The Security class serves as a toplevel class namespace.
   class Security
-      
+
     # The ACE class encapsulates an Access Control Entry, an element within
     # an Access Control List.
     class ACE
       # The version of the Win32::Security::ACE class.
       VERSION = '0.1.0'
 
-      # The ACE type, e.g. ACCESS_ALLOWED, ACCESS_DENIED, etc.
+      # The ACE type, e.g. ACCESS_ALLOWED, ACCESS_DENIED, etc. This is an integer.
       attr_accessor :ace_type
 
-      # The ACE mask, e.g. INHERITED_ACE
-      attr_accessor :ace_mask
-
-      # Standard access rights, e.g. GENERIC_READ, GENERIC_WRITE, etc 
+      # Standard access rights, e.g. GENERIC_READ, GENERIC_WRITE, etc.
+      # This is an integer.
       attr_accessor :access_mask
 
-      # Bit flags that indicate whether the ObjectType and
-      # InheritedObjectType members are present. This value is set
-      # internally based on the values passed to the ACE#object_type or
-      # ACE#inherited_object_type methods, if any.
+      # Bit flags associated with the ACE, e.g. OBJECT_INHERIT_ACE, etc.
+      # This is an integer.
       attr_reader :flags
 
-      # A Win32::Security::GUID object that identifies the type of child
-      # object that can inherit the ACE. 
-      attr_accessor :object_type
-
-      attr_accessor :inherited_object_type
-
-      def initialize
+      # Creates and returns an ACE object.
+      #
+      def initialize(access_mask, ace_type, flags)
+        @access_mask = access_mask
+        @ace_type = ace_type
+        @flags = flags
         yield self if block_given?
       end
+
+      # Returns the type of ace as a string, e.g. "ACCESS_ALLOWED_TYPE_ACE".
+      #
+      def ace_type_string
+        case @ace_type
+          when 0x0
+            'ACCESS_ALLOWED_ACE_TYPE'
+          when 0x1
+            'ACCESS_DENIED_ACE_TYPE'
+          when 0x2
+            'SYSTEM_AUDIT_ACE_TYPE'
+          when 0x3
+            'SYSTEM_ALARM_ACE_TYPE'
+          when 0x4
+            'ACCESS_ALLOWED_COMPOUND_ACE_TYPE'
+          when 0x5
+            'ACCESS_ALLOWED_OBJECT_ACE_TYPE'
+          when 0x6
+            'ACCESS_DENIED_OBJECT_ACE_TYPE'
+          when 0x7
+            'SYSTEM_AUDIT_OBJECT_ACE_TYPE'
+          when 0x8
+            'SYSTEM_ALARM_OBJECT_ACE_TYPE'
+          when 0x9
+            'ACCESS_ALLOWED_CALLBACK_ACE_TYPE'
+          when 0xA
+            'ACCESS_DENIED_CALLBACK_ACE_TYPE'
+          when 0xB
+            'ACCESS_ALLOWED_CALLBACK_OBJECT_ACE_TYPE'
+          when 0xC
+            'ACCESS_DENIED_CALLBACK_OBJECT_ACE_TYPE'
+          when 0xD
+            'SYSTEM_AUDIT_CALLBACK_ACE_TYPE'
+          when 0xE
+            'SYSTEM_ALARM_CALLBACK_ACE_TYPE'
+          when 0xF
+            'SYSTEM_AUDIT_CALLBACK_OBJECT_ACE_TYPE'
+          when 0x10
+            'SYSTEM_ALARM_CALLBACK_OBJECT_ACE_TYPE'
+        end
+      end
     end
   end
 end

data/lib/win32/security/acl.rb

@@ -1,7 +1,3 @@
-require File.join(File.dirname(__FILE__), 'windows', 'constants')
-require File.join(File.dirname(__FILE__), 'windows', 'structs')
-require File.join(File.dirname(__FILE__), 'windows', 'functions')
-
 # The Win32 module serves as a namespace only.
 module Win32
 
@@ -28,10 +24,10 @@ module Win32
       # encapsulates an ACL structure, including a binary representation of
       # the ACL itself, and the revision information.
       #
-      def initialize(revision = ACL_REVISION)
+      def initialize(size = 1024, revision = ACL_REVISION)
         acl = ACL_STRUCT.new
 
-        unless InitializeAcl(acl, acl.size, revision)
+        unless InitializeAcl(acl, size, revision)
           raise SystemCallError.new("InitializeAcl", FFI.errno)
         end
 
@@ -51,21 +47,87 @@ module Win32
         info[:AceCount]
       end
 
-      # Adds an access allowed ACE to the given +sid+. The +mask+ is a
-      # bitwise OR'd value of access rights.
+      # Returns a two element array that consists of the bytes in use and
+      # bytes free for the ACL.
+      #
+      def byte_info
+        info = ACL_SIZE_INFORMATION.new
+
+        unless GetAclInformation(@acl, info, info.size, AclSizeInformation)
+          raise SystemCallError.new("GetAclInformation", FFI.errno)
+        end
+
+        [info[:AclBytesInUse], info[:AclBytesFree]]
+      end
+
+      # Adds an access allowed ACE to the given +sid+, which can be a
+      # Win32::Security::SID object or a plain user or group name. If no
+      # sid is provided then the owner of the current process is used.
       #
-      # TODO: Move this into the SID class?
-      def add_access_allowed_ace(sid, mask=0)
-        unless AddAccessAllowedAce(@acl, @revision, mask, sid)
-          raise SystemCallError.new("AddAccessAllowedAce", FFI.errno)
+      # The +mask+ is a bitwise OR'd value of access rights.
+      #
+      # The +flags+ argument can be anyone of the following constants.
+      #
+      # * OBJECT_INHERIT_ACE
+      # * CONTAINER_INHERIT_ACE
+      # * NO_PROPAGATE_INHERIT_ACE
+      # * INHERIT_ONLY_ACE
+      # * INHERITED_ACE
+      #
+      # Example:
+      #
+      #   acl = Win32::Security::ACL.new
+      #   acl.add_access_allowed_ace('some_user', GENERIC_READ | GENERIC_WRITE)
+      #
+      def add_access_allowed_ace(sid=nil, mask=0, flags=nil)
+        if sid.is_a?(Win32::Security::SID)
+          sid = sid.sid
+        else
+          sid = Win32::Security::SID.new(sid).sid
+        end
+
+        if flags
+          unless AddAccessAllowedAceEx(@acl, @revision, flags, mask, sid)
+            raise SystemCallError.new("AddAccessAllowedAceEx", FFI.errno)
+          end
+        else
+          unless AddAccessAllowedAce(@acl, @revision, mask, sid)
+            raise SystemCallError.new("AddAccessAllowedAce", FFI.errno)
+          end
         end
+
+        sid
       end
 
-      # Adds an access denied ACE to the given +sid+.
+      # Adds an access denied ACE to the given +sid+, which can be a
+      # Win32::Security::SID object ora plain user or group name. If
+      # no sid is provided then the owner of the current process is used.
+      #
+      # The +mask+ is the bitwise OR'd value of access rights.
+      #
+      # The +flags+ argument can be any one of the following constants:
       #
-      def add_access_denied_ace(sid, mask=0)
-        unless AddAccessDeniedAce(@acl, @revision, mask, sid)
-          raise SystemCallError.new("AddAccessDeniedAce", FFI.errno)
+      # * OBJECT_INHERIT_ACE
+      # * CONTAINER_INHERIT_ACE
+      # * NO_PROPAGATE_INHERIT_ACE
+      # * INHERIT_ONLY_ACE
+      # * INHERITED_ACE
+      #
+      def add_access_denied_ace(sid=nil, mask=0, flags=nil)
+        if sid.is_a?(Win32::Security::SID)
+          sid = sid.sid
+        else
+          sid = Win32::Security::SID.new(sid).sid
+        end
+
+        if flags
+          unless AddAccessDeniedAceEx(@acl, @revision, flags, mask, sid)
+            raise SystemCallError.new("AddAccessDeniedAceEx", FFI.errno)
+          end
+        else
+          unless AddAccessDeniedAce(@acl, @revision, mask, sid)
+            raise SystemCallError.new("AddAccessDeniedAce", FFI.errno)
+          end
         end
       end
 
@@ -74,8 +136,7 @@ module Win32
       #
       # Returns the index if successful.
       #--
-      # This is untested and will require an actual implementation of
-      # Win32::Security::Ace before it can work properly.
+      # This won't work until we implement the ACE class.
       #
       def add_ace(ace, index=MAXDWORD)
         unless AddAce(@acl, @revision, index, ace, ace.length)
@@ -89,36 +150,49 @@ module Win32
       # 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.
       #
       def delete_ace(index=MAXDWORD)
-        unless DeleteAce(@ace, index)
+        unless DeleteAce(@acl, index)
           raise SystemCallError.new("DeleteAce", FFI.errno)
         end
 
         index
       end
 
-      # 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.
+      # Finds and returns an ACE object for the ACL at the given
+      # +index+. If no index is provided, then it returns an ACE object
+      # that corresponds to the first free byte of the ACL.
       #
-      def find_ace(index = nil)
-        pptr = FFI::MemoryPointer.new(:pointer)
-
-        if index.nil?
-          unless FindFirstFreeAce(@acl, pptr)
-            raise SystemCallError.new("DeleteAce", FFI.errno)
+      # If +raw+ is true, it will return an ACCESS_GENERIC_ACE struct,
+      # an FFI object that you can then access directly.
+      #
+      def find_ace(index = nil, raw = false)
+        result = nil
+
+        FFI::MemoryPointer.new(:pointer) do |pptr|
+          if index.nil?
+            unless FindFirstFreeAce(@acl, pptr)
+              raise SystemCallError.new("FindFirstFreeAce", FFI.errno)
+            end
+          else
+            unless GetAce(@acl, index, pptr)
+              raise SystemCallError.new("GetAce", FFI.errno)
+            end
           end
-        else
-          unless GetAce(@acl, index, pptr)
-            raise SystemCallError.new("GetAce", FFI.errno)
+
+          # There's no way to know what type of ACE it is at this point as far
+          # as I know, so we use a generic struct and use the AceType to figure
+          # it out later, or the users can.
+          ace = ACCESS_GENERIC_ACE.new(pptr.read_pointer)
+
+          if raw
+            result = ace
+          else
+            result = ACE.new(ace[:Mask], ace[:Header][:AceType], ace[:Header][:AceFlags])
           end
         end
 
-        pptr.read_pointer.address
+        result
       end
 
       # Sets the revision information level, where the +revision_level+
@@ -127,11 +201,12 @@ module Win32
       # Returns the revision level if successful.
       #
       def revision=(revision_level)
-        buf = FFI::MemoryPointer.new(:ulong)
-        buf.write_ulong(revision_level)
+        FFI::MemoryPointer.new(:ulong) do |buf|
+          buf.write_ulong(revision_level)
 
-        unless SetAclInformation(@acl, buf, buf.size, AclRevisionInformation)
-          raise SystemCallError.new("SetAclInformation", FFI.errno)
+          unless SetAclInformation(@acl, buf, buf.size, AclRevisionInformation)
+            raise SystemCallError.new("SetAclInformation", FFI.errno)
+          end
         end
 
         @revision = revision_level

data/lib/win32/security/sid.rb

@@ -1,6 +1,3 @@
-require File.join(File.dirname(__FILE__), 'windows', 'constants')
-require File.join(File.dirname(__FILE__), 'windows', 'functions')
-require File.join(File.dirname(__FILE__), 'windows', 'structs')
 require 'socket'
 
 # The Win32 module serves as a namespace only.
@@ -78,27 +75,35 @@ module Win32
       # Converts a binary SID to a string in S-R-I-S-S... format.
       #
       def self.sid_to_string(sid)
-        string_sid = FFI::MemoryPointer.new(:pointer)
+        result = nil
 
-        unless ConvertSidToStringSid(sid, string_sid)
-          raise SystemCallError.new("ConvertSidToStringSid", FFI.errno)
+        FFI::MemoryPointer.new(:pointer) do |string_sid|
+          unless ConvertSidToStringSid(sid, string_sid)
+            raise SystemCallError.new("ConvertSidToStringSid", FFI.errno)
+          end
+
+          result = string_sid.read_pointer.read_string
         end
 
-        string_sid.read_pointer.read_string
+        result
       end
 
       # Converts a string in S-R-I-S-S... format back to a binary SID.
       #
       def self.string_to_sid(string)
-        sid = FFI::MemoryPointer.new(:pointer)
+        result = nil
 
-        unless ConvertStringSidToSid(string, sid)
-          raise SystemCallError.new("ConvertStringSidToSid", FFI.errno)
-        end
+        FFI::MemoryPointer.new(:pointer) do |sid|
+          unless ConvertStringSidToSid(string, sid)
+            raise SystemCallError.new("ConvertStringSidToSid", FFI.errno)
+          end
 
-        ptr = sid.read_pointer
+          ptr = sid.read_pointer
 
-        ptr.read_bytes(GetLengthSid(ptr))
+          result = ptr.read_bytes(GetLengthSid(ptr))
+        end
+
+        result
       end
 
       # Creates a new SID with +authority+ and up to 8 +subauthorities+,
@@ -127,21 +132,25 @@ module Win32
         end
 
         size = GetSidLengthRequired(sub_authorities.length)
-        sid  = FFI::MemoryPointer.new(:uchar, size)
+        new_obj = nil
 
-        auth = SID_IDENTIFIER_AUTHORITY.new
-        auth[:Value][5] = authority
+        FFI::MemoryPointer.new(:uchar, size) do |sid|
+          auth = SID_IDENTIFIER_AUTHORITY.new
+          auth[:Value][5] = authority
 
-        unless InitializeSid(sid, auth, sub_authorities.length)
-          raise SystemCallError.new("InitializeSid", FFI.errno)
-        end
+          unless InitializeSid(sid, auth, sub_authorities.length)
+            raise SystemCallError.new("InitializeSid", FFI.errno)
+          end
 
-        sub_authorities.each_index do |i|
-          ptr = GetSidSubAuthority(sid, i)
-          ptr.write_ulong(sub_authorities[i])
+          sub_authorities.each_index do |i|
+            ptr = GetSidSubAuthority(sid, i)
+            ptr.write_ulong(sub_authorities[i])
+          end
+
+          new_obj = new(sid.read_string(size)) # Pass a binary string
         end
 
-        new(sid.read_string(size)) # Pass a binary string
+        new_obj
       end
 
       # Creates and returns a new Win32::Security::SID object, based on
@@ -182,13 +191,14 @@ module Win32
             if !bool && FFI.errno != ERROR_NO_TOKEN
               raise SystemCallError.new("OpenThreadToken", FFI.errno)
             else
-              ptoken = FFI::MemoryPointer.new(:uintptr_t)
+              ptoken.clear
               unless OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, ptoken)
                 raise SystemCallError.new("OpenProcessToken", FFI.errno)
               end
             end
 
             token = ptoken.read_pointer.to_i
+
             pinfo = FFI::MemoryPointer.new(:pointer)
             plength = FFI::MemoryPointer.new(:ulong)
 
@@ -196,7 +206,7 @@ module Win32
             GetTokenInformation(token, 1, pinfo, pinfo.size, plength)
 
             pinfo = FFI::MemoryPointer.new(plength.read_ulong)
-            plength = FFI::MemoryPointer.new(:ulong)
+            plength.clear
 
             # Second pass, actual call (1 is TokenOwner)
             unless GetTokenInformation(token, 1, pinfo, pinfo.size, plength)
@@ -241,6 +251,7 @@ module Win32
           end
         elsif ordinal_val < 10 # Assume it's a binary SID.
           account_ptr = FFI::MemoryPointer.from_string(account)
+
           bool = LookupAccountSid(
             host,
             account_ptr,
@@ -250,9 +261,12 @@ module Win32
             domain_size,
             use_ptr
           )
+
           unless bool
             raise SystemCallError.new("LookupAccountSid", FFI.errno)
           end
+
+          account_ptr.free
         else
           bool = LookupAccountName(
             host,
@@ -273,11 +287,11 @@ module Win32
           @sid = token_info.read_string
           @account = sid.read_string(sid.size).strip
         elsif ordinal_val < 10
-          @sid     = account
+          @sid = account
           @account = sid.read_string(sid.size).strip
         else
           length = GetLengthSid(sid)
-          @sid     = sid.read_string(length)
+          @sid = sid.read_string(length)
           @account = account
         end
 
@@ -297,13 +311,17 @@ module Win32
       # storage or transmission.
       #
       def to_s
-        ptr = FFI::MemoryPointer.new(:pointer)
+        string = nil
+
+        FFI::MemoryPointer.new(:pointer) do |ptr|
+          unless ConvertSidToStringSid(@sid, ptr)
+            raise SystemCallError.new("ConvertSidToStringSid", FFI.errno)
+          end
 
-        unless ConvertSidToStringSid(@sid, ptr)
-          raise SystemCallError.new("ConvertSidToStringSid", FFI.errno)
+          string = ptr.read_pointer.read_string
         end
 
-        ptr.read_pointer.read_string
+        string
       end
 
       alias to_str to_s

data/lib/win32/security/windows/constants.rb

@@ -5,6 +5,7 @@ module Windows
 
       TOKEN_QUERY = 8
       ERROR_NO_TOKEN = 1008
+      MAXDWORD = 0xFFFFFFFF
 
       # ACL Revisions
 
@@ -118,6 +119,66 @@ module Windows
       SidTypeInvalid        = 7
       SidTypeUnknown        = 8
       SidTypeComputer       = 9
+
+      # SDDL version information
+
+      SDDL_REVISION_1 = 1
+
+      # ACE flags
+
+      OBJECT_INHERIT_ACE                      = 0x1
+      CONTAINER_INHERIT_ACE                   = 0x2
+      NO_PROPAGATE_INHERIT_ACE                = 0x4
+      INHERIT_ONLY_ACE                        = 0x8
+      INHERITED_ACE                           = 0x10
+
+      # ACE Types
+
+      ACCESS_MIN_MS_ACE_TYPE                  = 0x0
+      ACCESS_ALLOWED_ACE_TYPE                 = 0x0
+      ACCESS_DENIED_ACE_TYPE                  = 0x1
+      SYSTEM_AUDIT_ACE_TYPE                   = 0x2
+      SYSTEM_ALARM_ACE_TYPE                   = 0x3
+      ACCESS_MAX_MS_V2_ACE_TYPE               = 0x3
+      ACCESS_ALLOWED_COMPOUND_ACE_TYPE        = 0x4
+      ACCESS_MAX_MS_V3_ACE_TYPE               = 0x4
+      ACCESS_MIN_MS_OBJECT_ACE_TYPE           = 0x5
+      ACCESS_ALLOWED_OBJECT_ACE_TYPE          = 0x5
+      ACCESS_DENIED_OBJECT_ACE_TYPE           = 0x6
+      SYSTEM_AUDIT_OBJECT_ACE_TYPE            = 0x7
+      SYSTEM_ALARM_OBJECT_ACE_TYPE            = 0x8
+      ACCESS_MAX_MS_OBJECT_ACE_TYPE           = 0x8
+      ACCESS_MAX_MS_V4_ACE_TYPE               = 0x8
+      ACCESS_MAX_MS_ACE_TYPE                  = 0x8
+      ACCESS_ALLOWED_CALLBACK_ACE_TYPE        = 0x9
+      ACCESS_DENIED_CALLBACK_ACE_TYPE         = 0xA
+      ACCESS_ALLOWED_CALLBACK_OBJECT_ACE_TYPE = 0xB
+      ACCESS_DENIED_CALLBACK_OBJECT_ACE_TYPE  = 0xC
+      SYSTEM_AUDIT_CALLBACK_ACE_TYPE          = 0xD
+      SYSTEM_ALARM_CALLBACK_ACE_TYPE          = 0xE
+      SYSTEM_AUDIT_CALLBACK_OBJECT_ACE_TYPE   = 0xF
+      SYSTEM_ALARM_CALLBACK_OBJECT_ACE_TYPE   = 0x10
+      ACCESS_MAX_MS_V5_ACE_TYPE               = 0x10
+
+      # Standard Access Rights
+
+      DELETE                       = 0x00010000
+      READ_CONTROL                 = 0x20000
+      WRITE_DAC                    = 0x40000
+      WRITE_OWNER                  = 0x80000
+      SYNCHRONIZE                  = 0x100000
+      STANDARD_RIGHTS_REQUIRED     = 0xf0000
+      STANDARD_RIGHTS_READ         = 0x20000
+      STANDARD_RIGHTS_WRITE        = 0x20000
+      STANDARD_RIGHTS_EXECUTE      = 0x20000
+      STANDARD_RIGHTS_ALL          = 0x1F0000
+      SPECIFIC_RIGHTS_ALL          = 0xFFFF
+      ACCESS_SYSTEM_SECURITY       = 0x1000000
+      MAXIMUM_ALLOWED              = 0x2000000
+      GENERIC_READ                 = 0x80000000
+      GENERIC_WRITE                = 0x40000000
+      GENERIC_EXECUTE              = 0x20000000
+      GENERIC_ALL                  = 0x10000000
     end
   end
 end

data/lib/win32/security/windows/functions.rb

@@ -72,14 +72,19 @@ module Windows
 
       ffi_lib :advapi32
 
+      attach_pfunc :AddAce, [:ptr, :dword, :dword, :ptr, :dword], :bool
       attach_pfunc :AddAccessAllowedAce, [:ptr, :dword, :dword, :ptr], :bool
-      attach_pfunc :AllocateAndInitializeSid,
-        [:ptr, :int, :dword, :dword, :dword, :dword, :dword, :dword, :dword, :dword, :ptr], :bool
+      attach_pfunc :AddAccessAllowedAceEx, [:ptr, :dword, :dword, :dword, :ptr], :bool
+      attach_pfunc :AddAccessDeniedAce, [:ptr, :dword, :dword, :ptr], :bool
+      attach_pfunc :AddAccessDeniedAceEx, [:ptr, :dword, :dword, :dword, :ptr], :bool
+      attach_pfunc :AllocateAndInitializeSid, [:ptr, :int, :dword, :dword, :dword, :dword, :dword, :dword, :dword, :dword, :ptr], :bool
       attach_pfunc :CheckTokenMembership, [:handle, :ptr, :ptr], :bool
       attach_pfunc :ConvertSidToStringSid, :ConvertSidToStringSidA, [:ptr, :ptr], :bool
       attach_pfunc :ConvertStringSidToSid, :ConvertStringSidToSidA, [:string, :ptr], :bool
+      attach_pfunc :DeleteAce, [:ptr, :dword], :bool
       attach_pfunc :EqualSid, [:ptr, :ptr], :bool
       attach_pfunc :FindFirstFreeAce, [:ptr, :ptr], :bool
+      attach_pfunc :GetAce, [:ptr, :dword, :ptr], :bool
       attach_pfunc :GetAclInformation, [:ptr, :ptr, :dword, :int], :bool
       attach_pfunc :GetLengthSid, [:ptr], :dword
       attach_pfunc :GetSidLengthRequired, [:uint], :dword
@@ -90,13 +95,16 @@ module Windows
       attach_pfunc :IsValidAcl, [:ptr], :bool
       attach_pfunc :IsValidSid, [:ptr], :bool
       attach_pfunc :IsWellKnownSid, [:ptr, :int], :bool
-      attach_pfunc :LookupAccountName, :LookupAccountNameA,
-        [:string, :string, :ptr, :ptr, :ptr, :ptr, :ptr], :bool
-      attach_pfunc :LookupAccountSid, :LookupAccountSidA,
-        [:string, :ptr, :ptr, :ptr, :ptr, :ptr, :ptr], :bool
+      attach_pfunc :LookupAccountName, :LookupAccountNameA, [:string, :string, :ptr, :ptr, :ptr, :ptr, :ptr], :bool
+      attach_pfunc :LookupAccountSid, :LookupAccountSidA, [:string, :ptr, :ptr, :ptr, :ptr, :ptr, :ptr], :bool
       attach_pfunc :OpenProcessToken, [:handle, :dword, :ptr], :bool
       attach_pfunc :OpenThreadToken, [:handle, :dword, :bool, :ptr], :bool
       attach_pfunc :SetAclInformation, [:ptr, :ptr, :dword, :int], :bool
+
+      attach_pfunc :ConvertSecurityDescriptorToStringSecurityDescriptor,
+        :ConvertSecurityDescriptorToStringSecurityDescriptorA, [:ptr, :dword, :dword, :ptr, :ptr], :bool
+      attach_pfunc :ConvertStringSecurityDescriptorToSecurityDescriptor,
+        :ConvertStringSecurityDescriptorToSecurityDescriptorA, [:string, :dword, :ptr, :ptr], :bool
     end
   end
 end

data/lib/win32/security/windows/structs.rb

@@ -30,6 +30,15 @@ module Windows
         )
       end
 
+      # Generic struct we made up and inspect later to determine type.
+      class ACCESS_GENERIC_ACE < FFI::Struct
+        layout(
+          :Header, ACE_HEADER,
+          :Mask, :ulong,
+          :SidStart, :ulong
+        )
+      end
+
       class ACCESS_ALLOWED_ACE < FFI::Struct
         layout(
           :Header, ACE_HEADER,
@@ -38,6 +47,14 @@ module Windows
         )
       end
 
+      class ACCESS_DENIED_ACE < FFI::Struct
+        layout(
+          :Header, ACE_HEADER,
+          :Mask, :ulong,
+          :SidStart, :ulong
+        )
+      end
+
       class ACCESS_ALLOWED_ACE2 < FFI::Struct
         layout(
           :Header, ACE_HEADER,
@@ -61,7 +78,15 @@ module Windows
         layout(
           :AceCount, :ulong,
           :AclBytesInUse, :ulong,
-          :AceBytesFree, :ulong
+          :AclBytesFree, :ulong
+        )
+      end
+
+      class SECURITY_ATTRIBUTES < FFI::Struct
+        layout(
+          :nLength, :ulong,
+          :lpSecurityDescriptor, :ulong,
+          :bInheritHandle, :bool
         )
       end
     end

data/test/test_ace.rb

@@ -0,0 +1,48 @@
+########################################################################
+# test_ace.rb
+#
+# Test suite for the Win32::Security::ACE class.
+########################################################################
+require 'test-unit'
+require 'win32/security'
+require 'win32/security/sid'
+require 'win32/security/acl'
+require 'win32/security/ace'
+
+class TC_Win32_Security_Ace < Test::Unit::TestCase
+  def setup
+    @ace = Win32::Security::ACE.new(1, 1, 1)
+  end
+
+  test "ACE version is set to the expected value" do
+    assert_equal('0.1.0', Win32::Security::ACE::VERSION)
+  end
+
+  test "ace_type basic functionality" do
+    assert_respond_to(@ace, :ace_type)
+    assert_equal(1, @ace.ace_type)
+  end
+
+  test "access_mask basic functionality" do
+    assert_respond_to(@ace, :access_mask)
+    assert_equal(1, @ace.access_mask)
+  end
+
+  test "flags basic functionality" do
+    assert_respond_to(@ace, :flags)
+    assert_equal(1, @ace.flags)
+  end
+
+  test "ace_type_string basic functionality" do
+    assert_respond_to(@ace, :ace_type_string)
+    assert_kind_of(String, @ace.ace_type_string)
+  end
+
+  test "ace_type_string returns the expected value" do
+    assert_equal('ACCESS_DENIED_ACE_TYPE', @ace.ace_type_string)
+  end
+
+  def teardown
+    @ace = nil
+  end
+end

data/test/test_acl.rb

@@ -54,11 +54,16 @@ class TC_Win32_Security_Acl < Test::Unit::TestCase
 
   test "find_ace basic functionality" do
     assert_respond_to(@acl, :find_ace)
-    assert_kind_of(Fixnum, @acl.find_ace)
   end
 
-  test "find_ace returns a sane value" do
-    assert_true(@acl.find_ace > 1000)
+  test "find_ace returns an ACE object if there is one to find" do
+    @acl.add_access_allowed_ace('Guest', Win32::Security::ACL::GENERIC_READ)
+    assert_kind_of(Win32::Security::ACE, @acl.find_ace)
+  end
+
+  test "find_ace accepts an integer argument" do
+    @acl.add_access_allowed_ace('Guest', Win32::Security::ACL::GENERIC_READ)
+    assert_kind_of(Win32::Security::ACE, @acl.find_ace(0))
   end
 
   test "revision getter basic functionality" do

data/test/test_security.rb

@@ -9,7 +9,7 @@ require 'win32/security'
 
 class TC_Win32_Security < Test::Unit::TestCase
   test "version constant is set to expected value" do
-    assert_equal('0.2.5', Win32::Security::VERSION)
+    assert_equal('0.3.0', Win32::Security::VERSION)
   end
 
   test "elevated security basic functionality" do

data/win32-security.gemspec

@@ -2,7 +2,7 @@ require 'rubygems'
 
 Gem::Specification.new do |spec|
   spec.name       = 'win32-security'
-  spec.version    = '0.2.5'
+  spec.version    = '0.3.0'
   spec.authors    = ['Daniel J. Berger', 'Park Heesob']
   spec.license    = 'Artistic 2.0'
   spec.email      = 'djberg96@gmail.com'
@@ -12,7 +12,6 @@ Gem::Specification.new do |spec|
   spec.files      = Dir['**/*'].reject{ |f| f.include?('git') }
 
   spec.extra_rdoc_files  = ['README', 'CHANGES', 'MANIFEST']
-  spec.rubyforge_project = 'win32utils'
    
   spec.add_dependency('ffi')
 
@@ -22,7 +21,7 @@ Gem::Specification.new do |spec|
    
   spec.description = <<-EOF
     The win32-security library provides an interface for dealing with
-    security related aspects of MS Windows. At the moment it provides an
-    interface for inspecting or creating SID's.
+    security related aspects of MS Windows, such as SID's, ACL's and
+    ACE's.
   EOF
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: win32-security
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Daniel J. Berger
@@ -9,68 +9,68 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-25 00:00:00.000000000 Z
+date: 2014-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.5.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.5.0
 - !ruby/object:Gem::Dependency
   name: sys-admin
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.0
 description: |2
       The win32-security library provides an interface for dealing with
-      security related aspects of MS Windows. At the moment it provides an
-      interface for inspecting or creating SID's.
+      security related aspects of MS Windows, such as SID's, ACL's and
+      ACE's.
 email: djberg96@gmail.com
 executables: []
 extensions: []
@@ -80,16 +80,17 @@ extra_rdoc_files:
 - MANIFEST
 files:
 - CHANGES
+- MANIFEST
+- README
+- Rakefile
+- lib/win32/security.rb
 - lib/win32/security/ace.rb
 - lib/win32/security/acl.rb
 - lib/win32/security/sid.rb
 - lib/win32/security/windows/constants.rb
 - lib/win32/security/windows/functions.rb
 - lib/win32/security/windows/structs.rb
-- lib/win32/security.rb
-- MANIFEST
-- Rakefile
-- README
+- test/test_ace.rb
 - test/test_acl.rb
 - test/test_security.rb
 - test/test_sid.rb
@@ -104,21 +105,22 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: win32utils
-rubygems_version: 2.0.3
+rubyforge_project: 
+rubygems_version: 2.4.2
 signing_key: 
 specification_version: 4
 summary: A library for dealing with aspects of Windows security.
 test_files:
+- test/test_ace.rb
 - test/test_acl.rb
 - test/test_security.rb
 - test/test_sid.rb