NAME

Win32::Security::SID - set of routines for SID manipulation

SYNOPSIS

  use Win32::Security::SID;

  Win32::Security::SID::ConvertSidToName($sid);
  Win32::Security::SID::ConvertSidToName(Win32::Security::SID::ConvertStringSidToSid($stringsid))

DESCRIPTION

This module provides functions for converting SIDs between binary and text formats and for converting between SIDs and Trustees (usernames).

Installation instructions

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

Function Reference

use Win32::Security::SID;

This has a side effect of use Win32; and of patching Win32::LookupAccountName to adjust the length of the SID properly as opposed to returning the entire 400 byte buffer.

ConvertSidToStringSid

This function is modeled on the Win32 API call of the same name. The Win32 API call, however, requires Win2K. This function takes a binary SID as a parameter (same format as returned by Win32::LookupAccountName) and returns the string form of the SID in the S-R-I-S-S format. It deals with IdentifierAuthority values greater than 2^32 by outputting them in hex (I have yet to run into any of these, but the spec allows for them). If the SID is inconsistent or non-existent, the function returns undef. The string form is mostly commonly used for display purposes and for mounting hives under HKEY_USERS.

ConvertStringSidToSid

This does the reverse of the above function. It takes a string SID as a parameter and returns the binary format. Again, if there are observable inconsistencies in the format, it will simply return undef.

ConvertNameToSid

This is basically a semi-intelligent wrapper around Win32::LookupAccountName. Of note, it uses undef for the server name to query, which means the query will execute against the local host. This will correctly operate on un-prefixed domain user accounts, presuming they don't have the same name as the local computer. If they do, the Win32::LookupAccountName returns the SID for the local computer, which is a problem. The $sidtype returned is checked to see that it is User, Group, Alias, or WellKnownGroup - if it is Domain or Computer, the function returns 'UNKNOWN_USERNAME', which helps to defend against this problem. The safest solution is to always use a full user/group name - domain_name\username. It returns the SID in binary format - if you need it in string SID format, call ConvertSidToStringSid.

If this function gets passed a username that looks like a StringSid (i.e. /^S(?:-\d+)+$/), it calls ConvertStringSidToSid and returns that result. This should only pose a problem if you have a very weird username and don't pass a domain name.

It uses a cache to remember previously asked for usernames (LookupAccountName is very processor intensive - watch LSASS.EXE spike if you make a lot of calls).

ConvertSidToName

This is basically a semi-intelligent wrapper around Win32::LookupAccountSID. It returns domain_name\username. In a nutshell, whatever gets returned by ConvertNameToSid is safely suppliable to ConvertSidToName. It accepts the SID in binary format - if you have a SID in string SID format, call ConvertStringSidtoSid first and pass the result.

It uses a cache to remember previously asked for SIDs (LookupAccountSID is very processor intensive - watch LSASS.EXE spike if you make a lot of calls).

AUTHOR

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