NAME

Win32::Security::Raw - low-level access Win32 Security API calls

SYNOPSIS

        use Win32::Security::Raw;

DESCRIPTION

This module provides access to a limited number of Win32 Security API calls. As I have need for other functions I will add them to the module. If anyone has suggestions, feel free to ask - I will be quite happy to extend this module.

Installation instructions

This installs as part of Win32-Security. See Win32::Security::NamedObject for more information.

It depends upon the Win32::API and Data::BitMask modules, which should be installable via PPM or available on CPAN.

Function Reference

AdjustTokenPrivileges

CopyMemory_Read

Uses RtlMoveMemory to read an arbitrary memory location. You should pass a pointer in the form of a Perl integer and the number of bytes to read from that location. The function will return the data read in a Perl string.

CopyMemory_Write

Uses RtlMoveMemory to write to an arbitrary memory location. You should pass a string that will be copied and a pointer in the form of a Perl integer. The caller is responsible for ensuring that the data to be written will not overrun the memory location.

GetCurrentProcess

Returns a handle to the CurrentProcess as an integer.

GetAclInformation

This expects a pointer to an ACL and an AclInformationClass value (i.e. 'AclSizeInformation' or 'AclRevisionInformation'). It returns the approriate data for the AclInformationClass value (the AclRevision in the case of AclRevisionInformation, the AceCount, AclBytesInUse, and AclBytesFree in the case of AclSizeInformation).

GetLengthSid

This accepts a pointer to a SID as an integer and returns the length.

GetNamedSecurityInfo

This expects an object name (i.e. a path to a file, registry key, etc.), an object type (i.e. 'SE_FILE_OBJECT'), and a SECURITY_INFORMATION mask (i.e. 'OWNER_SECURITY_INFORMATION|DACL_SECURITY_INFORMATION'). It returns pointers (as integers) to sidOwner, sidGroup, Dacl, Sacl, and the SecurityDescriptor. Some of these may be null pointers.

GetSecurityDescriptorControl

This expects a pointer to a SecurityDescriptor. It returns the Data::BitMask::break_mask form for the SECURITY_DESCRIPTOR_CONTROL mask.

InitializeSecurityDescriptor

Calls InitializeSecurityDescriptor on the passed pointer. dwRevision is optional - if omitted, revision 1 is used. Dies if the call fails.

LocalAlloc

Calls LocalAlloc with the passed uFlags and size. It returns the pointer, but dies if a null pointer is returned from the call. The uFlags parameter can be passed as either an integer or as legal LMEM_FLAGS.

LocalFree

Calls LocalFree on the passed pointer. The passed pointer should be in the form of a Perl integer.

LookupPrivilegeValue

Pass SystemName (undef permitted) and a privilege Name (i.e. SeRestorePrivilege). Returns the Luid.

OpenProcessToken

Pass ProcessHandle and DesiredAccess (TokenRights). Returns TokenHandle.

SetFileSecurity

Pass FileName, SecurityInfo, and SecurityDescriptor. Useful for setting permissions without propagating inheritable ACEs.

SetNamedSecurityInfo

This expects an object name (i.e. a path to a file, registry key, etc.), an object type (i.e. 'SE_FILE_OBJECT'), and a SECURITY_INFORMATION mask (i.e. 'OWNER_SECURITY_INFORMATION|DACL_SECURITY_INFORMATION'), and pointers (as integers) to sidOwner, sidGroup, Dacl, and Sacl. These may be null pointers if they are not referenced in the SECURITY_INFORMATION mask.

SetSecurityDescriptorDacl

Calls SetSecurityDescriptorDacl. Expects a pointer to a SecurityDescriptor, DaclPresent, Dacl, and DaclDefaulted. Dies if the call fails.

Data::BitMask Objects

The objects are accessed via class methods on Win32::Security. The Data::BitMask objects are created by the first call and lexically cached.

&Win32::Security::SE_OBJECT_TYPE

Win32 constants for SE_OBJECT_TYPE, along with the following aliases:

• FILE (SE_FILE_OBJECT)

• SERVICE (SE_SERVICE)

• PRINTER (SE_PRINTER)

• REG (SE_REGISTRY_KEY)

• REGISTRY (SE_REGISTRY_KEY)

• SHARE (SE_LMSHARE)

&Win32::Security::SECURITY_INFORMATION

&Win32::Security::SECURITY_DESCRIPTOR_CONTROL

&Win32::Security::ACL_INFORMATION_CLASS

&Win32::Security::TokenRights

&Win32::Security::LUID_ATTRIBUTES

&Win32::Security::LMEM_FLAGS

AUTHOR

Toby Ovod-Everett, toby@ovod-everett.org

cpanm Win32::Security::SID

perl -MCPAN -e shell
install Win32::Security::SID