Main Page   Namespace List   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

fksec Namespace Reference

The fksec namespace contains all identifiers, except macros, declared by this class library. More...


Compounds

class  fksec::ace
class  fksec::acl
class  fksec::ex
struct  fksec::ex::Hop
class  fksec::priv
class  fksec::sd
class  fksec::sid
class  fksec::token
class  fksec::token_group

Typedefs

typedef std::vector<fksec::ace> AceList
 shorthand for a list of fksec::ace. More...

typedef fksec::AceList::iterator AceListIter
 shorthand for an iterator into a list of fksec::ace. More...

typedef fksec::AceList::reverse_iterator AceListRevIter
 shorthand for a reverse iterator into a list of fksec::ace. More...

typedef fksec::AceList::const_iterator AceListConstIter
 shorthand for a read-only iterator into a list of fksec::ace. More...

typedef std::string fkstr
 fkstr is a synonym for the ANSI string in the ambient character size. More...

typedef std::ostream fkostream
 fkostream is a synonym for the ANSI ostream in the ambient character size. More...

typedef std::vector<fksec::sid> SidList
 SidList is an alias for a vector of fksec::sid objects. More...

typedef std::vector<token_group> group_list
typedef std::vector<priv> privilege_list

Enumerations

enum  Errcode {
  errNone,
  errBadHopIndex,
  errTooManySubAuths,
  errInvalidSid,
  errInvalidSubAuthIndex,
  errNoMemory,
  errBufferTooSmall,
  errInvalidAce,
  errInvalidAcl,
  errInvalidAceIndex,
  errStubbornPriv,
  errQueryToken,
  errDupTokenHandle,
  errOpenToken,
  errCloseToken,
  errInvalidPriv,
  errUnreadableSD,
  errUnwritableSD,
  errInvalidSD,
  errNoPrefixSid,
  errInvalidHandle,
  errAdjustToken,
  errNetApi32,
  errMaxError
}
 enumerates the principal type of an exception object. More...


Functions

fkostream& operator<< ( fkostream &o, const ace &a )
 GUID inserter. More...

fkostream& operator<< ( fkostream &o, const acl &a )
 dumps *this. More...

void GetFileSecurity ( const TCHAR *filename, SECURITY_INFORMATION whichParts, sd &sd )
 retrieves a file's security descriptor. More...

void SetFileSecurity ( const TCHAR *filename, SECURITY_INFORMATION whichParts, const sd &sd )
 sets a file's security descriptor. More...

void GetKernelObjectSecurity ( HANDLE h, SECURITY_INFORMATION whichParts, sd &sd )
 retrieves a kernel object's security descriptor. More...

void SetKernelObjectSecurity ( HANDLE h, SECURITY_INFORMATION whichParts, const sd &sd )
 sets a kernel object's security descriptor. More...

void GetUserObjectSecurity ( HANDLE h, SECURITY_INFORMATION whichParts, sd &sd )
 retrieves a user object's security descriptor. More...

void SetUserObjectSecurity ( HANDLE h, SECURITY_INFORMATION whichParts, const sd &sd )
 sets a user object's security descriptor. More...

void QueryServiceObjectSecurity ( SC_HANDLE hSvc, SECURITY_INFORMATION whichParts, sd &sd )
 retrieves a service's security descriptor. More...

void SetServiceObjectSecurity ( SC_HANDLE hSvc, SECURITY_INFORMATION whichParts, const sd &sd )
 sets a service's security descriptor. More...

void RegGetKeySecurity ( HKEY hk, SECURITY_INFORMATION whichParts, sd &sd )
 retrieves a registry key's security descriptor. More...

void RegSetKeySecurity ( HKEY hk, SECURITY_INFORMATION whichParts, const sd &sd )
 sets a registry key's security descriptor. More...

void AdsGetObjectSecurity ( const TCHAR *AdsPath, SECURITY_INFORMATION whichParts, sd &sd )
 retrieves an Active Directory Object's security descriptor. More...

void AdsSetObjectSecurity ( const TCHAR *AdsPath, SECURITY_INFORMATION whichParts, const sd &sd )
 sets an Active Directory object's security descriptor. More...

fkostream& operator<< ( fkostream &o, const ex& e )
 dumps this exception to a stream. More...

fkostream& operator<< ( fkostream &o, const priv& p )
 dumps interesting factoids about a priv instance into an ostream or wostream. More...

fkostream& operator<< ( fkostream &o, const sd &s )
fkostream& operator<< ( fkostream &o, const sid &s )
 Inserts a textual representation, suitable for debugging, into an output stream. More...

std::auto_ptr<WCHAR> Ansi2Unicode (const char * psz )
 converts an ANSI string into a Unicode string. More...

std::auto_ptr<char> Unicode2Ansi (const WCHAR * psz)
 converts a Unicode string into an ANSI string. More...

fkostream& operator<< ( fkostream &o, const GUID &g )
 GUID inserter.

fkostream& operator<< ( fkostream &o, const token & t )
fkostream& operator<< ( fkostream &o, const token_group & g )

Variables

const int initialBufferSize = 2048

Detailed Description

The fksec namespace contains all identifiers, except macros, declared by this class library.

Typedef Documentation

typedef std::vector<fksec::ace> fksec::AceList
 

shorthand for a list of fksec::ace.

Definition at line 136 of file acl.h.

typedef fksec::AceList::const_iterator fksec::AceListConstIter
 

shorthand for a read-only iterator into a list of fksec::ace.

Definition at line 142 of file acl.h.

typedef fksec::AceList::iterator fksec::AceListIter
 

shorthand for an iterator into a list of fksec::ace.

Definition at line 138 of file acl.h.

typedef fksec::AceList::reverse_iterator fksec::AceListRevIter
 

shorthand for a reverse iterator into a list of fksec::ace.

Definition at line 140 of file acl.h.

typedef std::vector<fksec::sid> fksec::SidList
 

SidList is an alias for a vector of fksec::sid objects.

Definition at line 60 of file sid.h.

typedef std::ostream fksec::fkostream
 

fkostream is a synonym for the ANSI ostream in the ambient character size.

Definition at line 86 of file fksec.h.

typedef std::string fksec::fkstr
 

fkstr is a synonym for the ANSI string in the ambient character size.

Definition at line 84 of file fksec.h.

typedef std::vector<token_group> fksec::group_list
 

Definition at line 134 of file token.h.

typedef std::vector<priv> fksec::privilege_list
 

Definition at line 135 of file token.h.

Enumeration Type Documentation

enum fksec::Errcode
 

enumerates the principal type of an exception object.

Enumeration values:
errNone   no error. You should never see this; it is there only so I can detect uninitialized error codes during development.
errBadHopIndex   hop index out of range. This one is thrown if you access the hop list of an exception object with an out-of-range index.
errTooManySubAuths   too many subauthorities in SID. NT defines a limit on the number of subauthorities in a SID (SID_MAX_SUB_AUTHORITIES); errTooManySubAuths is the reward for exceeding this limit.
errInvalidSid   uninitialized or invalid SID. This one gets thrown every time you try to use an invalid SID, look up an inexistent user, look up the user name for an inexistent SID, and so on. "Using" and invalid sid includes using it in an ace, which might get used in an acl, which might be plugged into a security descriptor.
errInvalidSubAuthIndex   aubauthority index out of range. Thrown if you try to get or set a subauthority of a sid that is not present - basically, an index out-of-range error.
errNoMemory   out of memory. Some of the methods for all classes need dynamically allocated memory, most notably the MakeFoo() functions, where Foo is PSID, PACE, PACL, PSD as appropriate. Other uses of dynamically allocated memory include buffers for name lookups in the sid class, and chunks for retrieving security descriptors in the apis.cpp functions. By now you can guess what happens if such memory as is needed cannot be allocated.
errBufferTooSmall   buffer too small. This happens when you call an object's StoreFoo() method to fill a buffer supplied by you, and the size you pass is not sufficient. Your choices are to either ask beforehand (all objects support a GetLength() method, and the acl object even has two different ones), allocating a sufficiently large buffer, or to handle the exception, get the required size from the exception's GetData() function, and proceed from there.
errInvalidAce   ACE invalid. This means that you tried to set invalid inheritance flags, an invalid ACE type, or the like. Invalid users or SIDs get an errInvalidSid instead.
errInvalidAcl   ACL invalid. Expect this exception when you feed invalid ACLs to an acl object. Note that invalid users or SIDs get an errInvalidSid instead.
errInvalidAceIndex   ACE index out of range. The index passed to GetAce() or SetAce() (of an acl object) is out-of-range.
errStubbornPriv   cannot change privilege state. A privilege refused to let us set its state (to enabled or disabled).
errQueryToken   cannot query privilege state. A privilege's state could not be retrieved. This should not happen; if the object cannot open a token handle for TOKEN_QUERY, an errOpenToken exception is thrown, and if the object did successfully open the token handle, this error should not happen.
errDupTokenHandle   cannot create duplicate token handle. If an already-opened token handle is passed to a priv object, the object attempts to create a duplicate for its own use. This error is what you get if the operation fails.
errOpenToken   failed to open process and thread tokens. If you leave a priv object's token handle as zero, it attempts to open the current thread or process token. If this fails, you get an errOpenToken exception.
errCloseToken   cannot close token. In theory, this should not happen - assuming, that is, that I don't pass invalid handles around.
errInvalidPriv   invalid or unknown privilege. The privilege you asked for doesn't exist.
errUnreadableSD   cannot grab an object's SD. Thrown by the functions in apis.cpp - a security descriptor could not be read off an object.
errUnwritableSD   cannot write an object's SD. Thrown by the functions in apis.cpp - a security descriptor could not be written to an object.
errInvalidSD   uninitialized or invalid SID. What can I say? I am really running out of platitudes by now ...
errNoPrefixSid   cannot find local domain's prefix SID. Raised by some sid lookup functions if the attempt of getting a machine's domain SID (with NetUserModalsGet()) fails. Call ex::GetErrWin32() for the precise error code.
errInvalidHandle   invalid token handle. Raised by some of the token functions.
errAdjustToken   AdjustToken() failed. Raised by some of the token functions.
errNetApi32   NetUser*() failed. Raised by sid::Members() and sid::MemberOf(), if one of the NetApi32 calls fails. Call ex::GetErrWin32() for the precise error code.
errMaxError   sentinel You should never see this in an exception. It serves mainly to check indexes into the error string array.

Definition at line 46 of file ex.h.

00047     {
00051         errNone,
00052 
00056         errBadHopIndex,
00057 
00062         errTooManySubAuths,
00063 
00070         errInvalidSid,
00071 
00075         errInvalidSubAuthIndex,
00076 
00085         errNoMemory,
00086 
00095         errBufferTooSmall,
00096 
00101         errInvalidAce,
00102 
00106         errInvalidAcl,
00107 
00110         errInvalidAceIndex,
00111 
00114         errStubbornPriv,
00115 
00121         errQueryToken,
00122 
00127         errDupTokenHandle,
00128 
00133         errOpenToken,
00134 
00138         errCloseToken,
00139 
00142         errInvalidPriv,
00143 
00147         errUnreadableSD,
00148 
00152         errUnwritableSD,
00153 
00156         errInvalidSD,
00157 
00162         errNoPrefixSid,
00163 
00166         errInvalidHandle,
00167 
00170         errAdjustToken,
00171 
00175         errNetApi32,
00176 
00180         errMaxError
00181     }

Function Documentation

void fksec::AdsGetObjectSecurity ( const TCHAR * AdsPath,
SECURITY_INFORMATION whichParts,
sd & sd )
 

retrieves an Active Directory Object's security descriptor.

AdsGetObjectSecurity() reads the security descriptor for an object stored in the Windows 2000 Active Directory. As with the other functions contained here, if the first attempt returns ERROR_PRIVILEGE_NOT_HELD, then it is retried with SeSecurityPrivilege enabled.

Parameters:
AdsPath   is the X.500 Format name of the object you which to fetch the SD for e.g. "OU=test2,OU=test1,DC=simonfell,DC=com". Whilst the documentation for GetNamedSecurityInfo (the underlying API call used) indicates that you can specify the name in the ADSI Path format ( e.g. "\\simonfell.com\test1\test2" ), I've yet to see it work.
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be retrieved; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object which is to receive the security descriptor.
Exceptions:
errUnreadableSd  
additionally   any that other fksec classes may throw (unlikely)
Author(s):
Simon Fell <simon@zaks.demon.co.uk>

Definition at line 812 of file apis.cpp.

00813 {
00814     PSECURITY_DESCRIPTOR psd = 0 ;
00815     DWORD rc;
00816     bool haveRetriedPrivilege = false ;
00817     bool oldSecPrivState = false;
00818     priv secPriv;
00819 
00820     try { secPriv = _T( "SeSecurityPrivilege" ); }
00821     RETHROWEX( "fksec::AdsGetObjectSecurity(): cannot identify SeSecurityPrivilege" )
00822 
00823     for ( ; ; )
00824     {
00825         rc = GetNamedSecurityInfo ( const_cast<TCHAR *>(AdsPath), SE_DS_OBJECT_ALL, whichParts, NULL, NULL, NULL, NULL, (void **)&psd ) ;
00826 
00827         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00828         {
00829             try { oldSecPrivState = secPriv.Enable(); }
00830             catch ( ex *e ) { delete e; }
00831             haveRetriedPrivilege = true;
00832         }
00833         else
00834             break; // unrecoverable
00835     }
00836 
00837     if ( 0 == rc )
00838     {
00839         sd = (SECURITY_DESCRIPTOR *)psd;
00840         LocalFree ( psd ) ;
00841     }
00842     
00843     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00844     {
00845         try { secPriv.SetState( oldSecPrivState ); }
00846         catch ( ex *e ) { delete e; } // just ignore errors here
00847     }
00848 
00849     if ( rc )
00850         throw NEWEX32( errUnreadableSD, "fksec::AdsGetObjectSecurity(): cannot read SD, see ex::GetErrWin32()", rc );
00851 }

void fksec::AdsSetObjectSecurity ( const TCHAR * AdsPath,
SECURITY_INFORMATION whichParts,
const sd & sd )
 

sets an Active Directory object's security descriptor.

AdsSetObjectSecurity() sets the security descriptor on an object stored in the Windows 2000 Active Direcotry. As with the other functions contained here, if the first attempt returns ERROR_PRIVILEGE_NOT_HELD, then it is retried with SeSecurityPrivilege enabled.

Parameters:
AdsPath   is the X.500 Format name of the object you which to fetch the SD for e.g. "OU=test2,OU=test1,DC=simonfell,DC=com". Whilst the documentation for GetNamedSecurityInfo (the underlying API call used) indicates that you can specify the name in the ADSI Path format ( e.g. "\\simonfell.com\test1\test2" ), I've yet to see it work.
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be set; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object representing the security descriptor to be applied.
Exceptions:
errUnwritableSd  
additionally   any that other fksec classes may throw (unlikely)
Author(s):
Simon Fell <simon@zaks.demon.co.uk>

Definition at line 877 of file apis.cpp.

00878 {
00879     DWORD rc;
00880     bool haveRetriedPrivilege = false;
00881     bool oldSecPrivState = false;
00882     priv secPriv;
00883 
00884     try { secPriv = _T( "SeSecurityPrivilege" ); }
00885     RETHROWEX( "fksec::AdsSetObjectSecurity(): cannot identify SeSecurityPrivilege" )
00886 
00887     for ( ; ; )
00888     {
00889         rc = SetNamedSecurityInfo ( const_cast<TCHAR *>(AdsPath), SE_DS_OBJECT_ALL, whichParts, sd.GetOwnerSid(), sd.GetGroupSid(), sd.GetDacl(), sd.GetSacl() ) ;
00890 
00891         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00892         {
00893             try { oldSecPrivState = secPriv.Enable(); }
00894             catch ( ex *e ) { delete e; }
00895             haveRetriedPrivilege = true;
00896         }
00897         else
00898             break; // unrecoverable or all OK
00899     }
00900 
00901     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00902     {
00903         try { secPriv.SetState( oldSecPrivState ); }
00904         catch ( ex *e ) { delete e; } // just ignore errors here
00905     }
00906 
00907     if ( rc )
00908         throw NEWEX32( errUnwritableSD, "fksec::AdsSetObjectSecurity(): cannot write SD, see ex::GetErrWin32()", rc );
00909 }

std::auto_ptr< WCHAR > fksec::Ansi2Unicode ( const char * psz )
 

converts an ANSI string into a Unicode string.

Takes an ANSI string, and returns a Unicode string. this is mainly needed for calls to NetApi32, which are Unicode only

Parameters:
psz   a standard NULL terminated ANSI string
Returns:
a Unicode char string, wrapped in a std::auto_ptr, which will free the string memory when it goes out of scope

Definition at line 16 of file strconv.cpp.

00017 {
00018     int cb = MultiByteToWideChar ( CP_ACP, 0, psz, -1, NULL, 0 ) ;
00019     std::auto_ptr<WCHAR> szdest ( new WCHAR [cb] ) ;
00020     MultiByteToWideChar ( CP_ACP, 0, psz, -1, szdest.get(), cb ) ;
00021     return szdest ;
00022 }

void fksec::GetFileSecurity ( const TCHAR * filename,
SECURITY_INFORMATION whichParts,
sd & sd )
 

retrieves a file's security descriptor.

GetFileSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a pre-allocated buffer (and its size) for a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd and fills it in
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
filename   the name of the file for which you wish to retrieve the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be retrieved; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object which is to receive the security descriptor.
Exceptions:
errUnreadableSd  
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 63 of file apis.cpp.

00064 {
00065     SECURITY_DESCRIPTOR *psd;
00066     DWORD needed, rc;
00067     bool haveRetriedPrivilege = false, haveRetriedSize = false;
00068     bool oldSecPrivState = false;
00069     priv secPriv;
00070 
00071     try { secPriv = _T( "SeSecurityPrivilege" ); }
00072     RETHROWEX( "fksec::GetFileSecurity(): cannot identify SeSecurityPrivilege" )
00073 
00074     needed = initialBufferSize;
00075     psd = (SECURITY_DESCRIPTOR *) new byte[initialBufferSize];
00076 
00077     for ( ; ; )
00078     {
00079         if ( ::GetFileSecurity( filename, whichParts, psd, needed, &needed ) )
00080             rc = 0;
00081         else
00082             rc = GetLastError();
00083 
00084         if ( rc == ERROR_INSUFFICIENT_BUFFER && ! haveRetriedSize )
00085         {
00086             delete [] (byte *) psd;
00087             psd = (SECURITY_DESCRIPTOR *) new byte[needed];
00088             haveRetriedSize = true;
00089         }
00090         else if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00091         {
00092             try { oldSecPrivState = secPriv.Enable(); }
00093             catch ( ex *e ) { delete e; }
00094             haveRetriedPrivilege = true;
00095         }
00096         else
00097             break; // unrecoverable or all OK
00098     }
00099 
00100     if ( rc == 0 )
00101         sd = psd;
00102 
00103     delete [] (byte *) psd;
00104 
00105     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00106     {
00107         try { secPriv.SetState( oldSecPrivState ); }
00108         catch ( ex *e ) { delete e; } // just ignore errors here
00109     }
00110 
00111     if ( rc )
00112         throw NEWEX32( errUnreadableSD, "fksec::GetFileSecurity(): cannot read SD, see ex::GetErrWin32()", rc );
00113 }

void fksec::GetKernelObjectSecurity ( HANDLE h,
SECURITY_INFORMATION whichParts,
sd & sd )
 

retrieves a kernel object's security descriptor.

GetKernelObjectSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a pre-allocated buffer (and its size) for a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd and fills it in
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
h   a handle to the kernel object for which you wish to retrieve the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be retrieved; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object which is to receive the security descriptor.
Exceptions:
errUnreadableSd  
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 215 of file apis.cpp.

00216 {
00217     SECURITY_DESCRIPTOR *psd;
00218     DWORD needed, rc;
00219     bool haveRetriedPrivilege = false, haveRetriedSize = false;
00220     bool oldSecPrivState = false;
00221     priv secPriv;
00222 
00223     try { secPriv = _T( "SeSecurityPrivilege" ); }
00224     RETHROWEX( "fksec::GetKernelObjectSecurity(): cannot identify SeSecurityPrivilege" )
00225 
00226     needed = initialBufferSize;
00227     psd = (SECURITY_DESCRIPTOR *) new byte[initialBufferSize];
00228 
00229     for ( ; ; )
00230     {
00231         if ( ::GetKernelObjectSecurity( h, whichParts, psd, needed, &needed ) )
00232             rc = 0;
00233         else
00234             rc = GetLastError();
00235 
00236         if ( rc == ERROR_INSUFFICIENT_BUFFER && ! haveRetriedSize )
00237         {
00238             delete [] (byte *) psd;
00239             psd = (SECURITY_DESCRIPTOR *) new byte[needed];
00240             haveRetriedSize = true;
00241         }
00242         else if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00243         {
00244             try { oldSecPrivState = secPriv.Enable(); }
00245             catch ( ex *e ) { delete e; }
00246             haveRetriedPrivilege = true;
00247         }
00248         else
00249             break; // unrecoverable or just fine
00250     }
00251 
00252     if ( rc == 0 )
00253         sd = psd;
00254 
00255     delete [] (byte *) psd;
00256 
00257     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00258     {
00259         try { secPriv.SetState( oldSecPrivState ); }
00260         catch ( ex *e ) { delete e; } // just ignore errors here
00261     }
00262 
00263     if ( rc )
00264         throw NEWEX32( errUnreadableSD, "fksec::GetKernelObjectSecurity(): cannot read SD, see ex::GetErrWin32()", rc );
00265 }

void fksec::GetUserObjectSecurity ( HANDLE h,
SECURITY_INFORMATION whichParts,
sd & sd )
 

retrieves a user object's security descriptor.

GetUserObjectSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a pre-allocated buffer (and its size) for a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd and fills it in
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
h   a handle to the user object for which you wish to retrieve the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be retrieved; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object which is to receive the security descriptor.
Exceptions:
errUnreadableSd  
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 367 of file apis.cpp.

00368 {
00369     SECURITY_DESCRIPTOR *psd;
00370     DWORD needed, rc;
00371     bool haveRetriedPrivilege = false, haveRetriedSize = false;
00372     bool oldSecPrivState = false;
00373     priv secPriv;
00374 
00375     try { secPriv = _T( "SeSecurityPrivilege" ); }
00376     RETHROWEX( "fksec::GetUserObjectSecurity(): cannot identify SeSecurityPrivilege" )
00377 
00378     needed = initialBufferSize;
00379     psd = (SECURITY_DESCRIPTOR *) new byte[initialBufferSize];
00380 
00381     for ( ; ; )
00382     {
00383         if ( ::GetUserObjectSecurity( h, &whichParts, psd, needed, &needed ) )
00384             rc = 0;
00385         else
00386             rc = GetLastError();
00387 
00388         if ( rc == ERROR_INSUFFICIENT_BUFFER && ! haveRetriedSize )
00389         {
00390             delete [] (byte *) psd;
00391             psd = (SECURITY_DESCRIPTOR *) new byte[needed];
00392             haveRetriedSize = true;
00393         }
00394         else if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00395         {
00396             try { oldSecPrivState = secPriv.Enable(); }
00397             catch ( ex *e ) { delete e; }
00398             haveRetriedPrivilege = true;
00399         }
00400         else
00401             break; // unrecoverable
00402     }
00403 
00404     if ( rc == 0 )
00405         sd = psd;
00406 
00407     delete [] (byte *) psd;
00408 
00409     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00410     {
00411         try { secPriv.SetState( oldSecPrivState ); }
00412         catch ( ex *e ) { delete e; } // just ignore errors here
00413     }
00414 
00415     if ( rc )
00416         throw NEWEX32( errUnreadableSD, "fksec::GetUserObjectSecurity(): cannot read SD, see ex::GetErrWin32()", rc );
00417 }

void fksec::QueryServiceObjectSecurity ( SC_HANDLE hSvc,
SECURITY_INFORMATION whichParts,
sd & sd )
 

retrieves a service's security descriptor.

GetServiceObjectSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a pre-allocated buffer (and its size) for a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd and fills it in
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
hSvc   an SCM handle to the servoce entry for which you wish to retrieve the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be retrieved; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object which is to receive the security descriptor.
Exceptions:
errUnreadableSd  
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 519 of file apis.cpp.

00520 {
00521     SECURITY_DESCRIPTOR *psd;
00522     DWORD needed, rc;
00523     bool haveRetriedPrivilege = false, haveRetriedSize = false;
00524     bool oldSecPrivState = false;
00525     priv secPriv;
00526 
00527     try { secPriv = _T( "SeSecurityPrivilege" ); }
00528     RETHROWEX( "fksec::QueryServiceObjectSecurity(): cannot identify SeSecurityPrivilege" )
00529 
00530     needed = initialBufferSize;
00531     psd = (SECURITY_DESCRIPTOR *) new byte[initialBufferSize];
00532 
00533     for ( ; ; )
00534     {
00535         if ( ::QueryServiceObjectSecurity( hSvc, whichParts, psd, needed, &needed ) )
00536             rc = 0;
00537         else
00538             rc = GetLastError();
00539 
00540         if ( rc == ERROR_INSUFFICIENT_BUFFER && ! haveRetriedSize )
00541         {
00542             delete [] (byte *) psd;
00543             psd = (SECURITY_DESCRIPTOR *) new byte[needed];
00544             haveRetriedSize = true;
00545         }
00546         else if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00547         {
00548             try { oldSecPrivState = secPriv.Enable(); }
00549             catch ( ex *e ) { delete e; }
00550             haveRetriedPrivilege = true;
00551         }
00552         else
00553             break; // unrecoverable
00554     }
00555 
00556     if ( rc == 0 )
00557         sd = psd;
00558 
00559     delete [] (byte *) psd;
00560 
00561     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00562     {
00563         try { secPriv.SetState( oldSecPrivState ); }
00564         catch ( ex *e ) { delete e; } // just ignore errors here
00565     }
00566 
00567     if ( rc )
00568         throw NEWEX32( errUnreadableSD, "fksec::QueryServiceObjectSecurity(): cannot read SD, see ex::GetErrWin32()", rc );
00569 }

void fksec::RegGetKeySecurity ( HKEY hk,
SECURITY_INFORMATION whichParts,
sd & sd )
 

retrieves a registry key's security descriptor.

RegGetKeySecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a pre-allocated buffer (and its size) for a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd and fills it in
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
hk   a handle to the registry key for which you wish to retrieve the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be retrieved; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object which is to receive the security descriptor.
Exceptions:
errUnreadableSd  
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 671 of file apis.cpp.

00672 {
00673     SECURITY_DESCRIPTOR *psd;
00674     DWORD needed, rc;
00675     bool haveRetriedPrivilege = false, haveRetriedSize = false;
00676     bool oldSecPrivState = false;
00677     priv secPriv;
00678 
00679     try { secPriv = _T( "SeSecurityPrivilege" ); }
00680     RETHROWEX( "fksec::RegGetKeySecurity(): cannot identify SeSecurityPrivilege" )
00681 
00682     needed = initialBufferSize;
00683     psd = (SECURITY_DESCRIPTOR *) new byte[initialBufferSize];
00684 
00685     for ( ; ; )
00686     {
00687         rc = ::RegGetKeySecurity( hk, whichParts, psd, &needed );
00688 
00689         if ( rc == ERROR_INSUFFICIENT_BUFFER && ! haveRetriedSize )
00690         {
00691             delete [] (byte *) psd;
00692             psd = (SECURITY_DESCRIPTOR *) new byte[needed];
00693             haveRetriedSize = true;
00694         }
00695         else if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00696         {
00697             try { oldSecPrivState = secPriv.Enable(); }
00698             catch ( ex *e ) { delete e; }
00699             haveRetriedPrivilege = true;
00700         }
00701         else
00702             break; // unrecoverable
00703     }
00704 
00705     if ( rc == 0 )
00706         sd = psd;
00707 
00708     delete [] (byte *) psd;
00709 
00710     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00711     {
00712         try { secPriv.SetState( oldSecPrivState ); }
00713         catch ( ex *e ) { delete e; } // just ignore errors here
00714     }
00715 
00716     if ( rc )
00717         throw NEWEX32( errUnreadableSD, "fksec::RegGetKeySecurity(): cannot read SD, see ex::GetErrWin32()", rc );
00718 }

void fksec::RegSetKeySecurity ( HKEY hk,
SECURITY_INFORMATION whichParts,
const sd & sd )
 

sets a registry key's security descriptor.

RegSetKeySecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
hk   a handle to the registry key for which you wish to set the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be set; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object representing the security descriptor to be applied.
Exceptions:
errUnwritableSd  
errInvalidAcl   if the acl contains object ACE's
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 749 of file apis.cpp.

00750 {
00751     DWORD rc;
00752     bool haveRetriedPrivilege = false;
00753     bool oldSecPrivState = false;
00754     priv secPriv;
00755 
00756     if ( sd.GetDacl().IsObjectACL() )
00757         throw NEWEX(fksec::errInvalidAcl, "fksec::RegSetKeySecurity(): cannot write SD, DACL contains object ACE's" ) ;
00758     if ( sd.GetSacl().IsObjectACL() ) 
00759         throw NEWEX(fksec::errInvalidAcl, "fksec::RegSetKeySecurity(): cannot write SD, SACL contains object ACE's" ) ;
00760 
00761     try { secPriv = _T( "SeSecurityPrivilege" ); }
00762     RETHROWEX( "fksec::RegSetKeySecurity(): cannot identify SeSecurityPrivilege" )
00763 
00764     for ( ; ; )
00765     {
00766         rc = ::RegSetKeySecurity( hk, whichParts, (SECURITY_DESCRIPTOR *) sd );
00767 
00768         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00769         {
00770             try { oldSecPrivState = secPriv.Enable(); }
00771             catch ( ex *e ) { delete e; }
00772             haveRetriedPrivilege = true;
00773         }
00774         else
00775             break; // unrecoverable or all OK
00776     }
00777 
00778     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00779     {
00780         try { secPriv.SetState( oldSecPrivState ); }
00781         catch ( ex *e ) { delete e; } // just ignore errors here
00782     }
00783 
00784     if ( rc )
00785         throw NEWEX32( errUnwritableSD, "fksec::RegSetKeySecurity(): cannot write SD, see ex::GetErrWin32()", rc );
00786 }

void fksec::SetFileSecurity ( const TCHAR * filename,
SECURITY_INFORMATION whichParts,
const sd & sd )
 

sets a file's security descriptor.

SetFileSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
filename   the name of the file for which you wish to set the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be set; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object representing the security descriptor to be applied.
Exceptions:
errUnwritableSd  
errInvalidAcl   if the acl contains object ACE's
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 144 of file apis.cpp.

00145 {
00146     DWORD rc;
00147     bool haveRetriedPrivilege = false;
00148     bool oldSecPrivState = false;
00149     priv secPriv;
00150 
00151     if ( sd.GetDacl().IsObjectACL() )
00152         throw NEWEX(fksec::errInvalidAcl, "fksec::SetFileSecurity(): cannot write SD, DACL contains object ACE's" ) ;
00153     if ( sd.GetSacl().IsObjectACL() ) 
00154         throw NEWEX(fksec::errInvalidAcl, "fksec::SetFileSecurity(): cannot write SD, SACL contains object ACE's" ) ;
00155 
00156     try { secPriv = _T( "SeSecurityPrivilege" ); }
00157     RETHROWEX( "fksec::SetFileSecurity(): cannot identify SeSecurityPrivilege" )
00158 
00159     for ( ; ; )
00160     {
00161         if ( ::SetFileSecurity( filename, whichParts, (SECURITY_DESCRIPTOR *) sd ) )
00162             rc = 0;
00163         else
00164             rc = GetLastError();
00165 
00166         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00167         {
00168             try { oldSecPrivState = secPriv.Enable(); }
00169             catch ( ex *e ) { delete e; }
00170             haveRetriedPrivilege = true;
00171         }
00172         else
00173             break; // unrecoverable or all OK
00174     }
00175 
00176     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00177     {
00178         try { secPriv.SetState( oldSecPrivState ); }
00179         catch ( ex *e ) { delete e; } // just ignore errors here
00180     }
00181 
00182     if ( rc )
00183         throw NEWEX32( errUnwritableSD, "fksec::SetFileSecurity(): cannot write SD, see ex::GetErrWin32()", rc );
00184 }

void fksec::SetKernelObjectSecurity ( HANDLE h,
SECURITY_INFORMATION whichParts,
const sd & sd )
 

sets a kernel object's security descriptor.

SetKernelObjectSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
h   a handle to the kernel object for which you wish to set the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be set; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object representing the security descriptor to be applied.
Exceptions:
errUnwritableSd  
errInvalidAcl   if the acl contains object ACE's
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 296 of file apis.cpp.

00297 {
00298     DWORD rc;
00299     bool haveRetriedPrivilege = false;
00300     bool oldSecPrivState = false;
00301     priv secPriv;
00302 
00303     if ( sd.GetDacl().IsObjectACL() )
00304         throw NEWEX(fksec::errInvalidAcl, "fksec::SetKernelObjectSecurity(): cannot write SD, DACL contains object ACE's" ) ;
00305     if ( sd.GetSacl().IsObjectACL() ) 
00306         throw NEWEX(fksec::errInvalidAcl, "fksec::SetKernelObjectSecurity(): cannot write SD, SACL contains object ACE's" ) ;
00307 
00308     try { secPriv = _T( "SeSecurityPrivilege" ); }
00309     RETHROWEX( "fksec::SetKernelObjectSecurity(): cannot identify SeSecurityPrivilege" )
00310 
00311     for ( ; ; )
00312     {
00313         if ( ::SetKernelObjectSecurity( h, whichParts, (SECURITY_DESCRIPTOR *) sd ) )
00314             rc = 0;
00315         else
00316             rc = GetLastError();
00317 
00318         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00319         {
00320             try { oldSecPrivState = secPriv.Enable(); }
00321             catch ( ex *e ) { delete e; }
00322             haveRetriedPrivilege = true;
00323         }
00324         else
00325             break; // unrecoverable
00326     }
00327 
00328     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00329     {
00330         try { secPriv.SetState( oldSecPrivState ); }
00331         catch ( ex *e ) { delete e; } // just ignore errors here
00332     }
00333 
00334     if ( rc )
00335         throw NEWEX32( errUnwritableSD, "fksec::SetKernelObjectSecurity(): cannot write SD, see ex::GetErrWin32()", rc );
00336 }

void fksec::SetServiceObjectSecurity ( SC_HANDLE hSvc,
SECURITY_INFORMATION whichParts,
const sd & sd )
 

sets a service's security descriptor.

SetServiceObjectSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
hSvc   an SCM handle to the service for which you wish to set the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be set; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object representing the security descriptor to be applied.
Exceptions:
errUnwritableSd  
errInvalidAcl   if the acl contains object ACE's
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 600 of file apis.cpp.

00601 {
00602     DWORD rc;
00603     bool haveRetriedPrivilege = false;
00604     bool oldSecPrivState = false;
00605     priv secPriv;
00606 
00607     if ( sd.GetDacl().IsObjectACL() )
00608         throw NEWEX(fksec::errInvalidAcl, "fksec::SetServiceObjectSecurity(): cannot write SD, DACL contains object ACE's" ) ;
00609     if ( sd.GetSacl().IsObjectACL() ) 
00610         throw NEWEX(fksec::errInvalidAcl, "fksec::SetServiceObjectSecurity(): cannot write SD, SACL contains object ACE's" ) ;
00611 
00612     try { secPriv = _T( "SeSecurityPrivilege" ); }
00613     RETHROWEX( "fksec::SetServiceObjectSecurity(): cannot identify SeSecurityPrivilege" )
00614 
00615     for ( ; ; )
00616     {
00617         if ( ::SetServiceObjectSecurity( hSvc, whichParts, (SECURITY_DESCRIPTOR *) sd ) )
00618             rc = 0;
00619         else
00620             rc = GetLastError();
00621 
00622         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00623         {
00624             try { oldSecPrivState = secPriv.Enable(); }
00625             catch ( ex *e ) { delete e; }
00626             haveRetriedPrivilege = true;
00627         }
00628         else
00629             break; // unrecoverable
00630     }
00631 
00632     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00633     {
00634         try { secPriv.SetState( oldSecPrivState ); }
00635         catch ( ex *e ) { delete e; } // just ignore errors here
00636     }
00637 
00638     if ( rc )
00639         throw NEWEX32( errUnwritableSD, "fksec::SetServiceObjectSecurity(): cannot write SD, see ex::GetErrWin32()", rc );
00640 }

void fksec::SetUserObjectSecurity ( HANDLE h,
SECURITY_INFORMATION whichParts,
const sd & sd )
 

sets a user object's security descriptor.

SetUserObjectSecurity() mimics the behaviour of the NT API function of the same name, with only a few changes. These are:

  • Errors are not indicated by a FALSE return value and SetLastError() but are thrown as exceptions
  • Instead of a SECURITY_DESCRIPTOR, the function accepts a reference to an fksec::sd
  • It automatically enables SeSecurityPrivilege, if a first attempt at calling the NT function results in an ERROR_PRIVILEGE_NOT_HELD
Note that the function takes a reference to an fksec::sd as its last argument.
Parameters:
h   a handle to the user object for which you wish to set the security descriptor
whichParts   a set of bits, ORed together, indicating which elements of the security descriptor should be set; valid bits are, as of 24 Dec 1999: DACL_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, SACL_SECURITY_INFORMATION. NT5 also defines the following: PROTECTED_DACL_SECURITY_INFORMATION, PROTECTED_SACL_SECURITY_INFORMATION, UNPROTECTED_DACL_SECURITY_INFORMATION, UNPROTECTED_SACL_SECURITY_INFORMATION.
sd   a reference to the sd object representing the security descriptor to be applied.
Exceptions:
errUnwritableSd  
errInvalidAcl   if the acl contains object ACE's
additionally   any that other fksec classes may throw (unlikely, and usually the result of a bug of mine)

Definition at line 448 of file apis.cpp.

00449 {
00450     DWORD rc;
00451     bool haveRetriedPrivilege = false;
00452     bool oldSecPrivState = false;
00453     priv secPriv;
00454 
00455     if ( sd.GetDacl().IsObjectACL() )
00456         throw NEWEX(fksec::errInvalidAcl, "fksec::SetUserObjectSecurity(): cannot write SD, DACL contains object ACE's" ) ;
00457     if ( sd.GetSacl().IsObjectACL() ) 
00458         throw NEWEX(fksec::errInvalidAcl, "fksec::SetUserObjectSecurity(): cannot write SD, SACL contains object ACE's" ) ;
00459 
00460     try { secPriv = _T( "SeSecurityPrivilege" ); }
00461     RETHROWEX( "fksec::SetUserObjectSecurity(): cannot identify SeSecurityPrivilege" )
00462 
00463     for ( ; ; )
00464     {
00465         if ( ::SetUserObjectSecurity( h, &whichParts, (SECURITY_DESCRIPTOR *) sd ) )
00466             rc = 0;
00467         else
00468             rc = GetLastError();
00469 
00470         if ( rc == ERROR_PRIVILEGE_NOT_HELD && ! haveRetriedPrivilege )
00471         {
00472             try { oldSecPrivState = secPriv.Enable(); }
00473             catch ( ex *e ) { delete e; }
00474             haveRetriedPrivilege = true;
00475         }
00476         else
00477             break; // unrecoverable
00478     }
00479 
00480     if ( haveRetriedPrivilege ) // did we fuck with the privilege?
00481     {
00482         try { secPriv.SetState( oldSecPrivState ); }
00483         catch ( ex *e ) { delete e; } // just ignore errors here
00484     }
00485 
00486     if ( rc )
00487         throw NEWEX32( errUnwritableSD, "fksec::SetUserObjectSecurity(): cannot write SD, see ex::GetErrWin32()", rc );
00488 }

std::auto_ptr< char > fksec::Unicode2Ansi ( const WCHAR * psz )
 

converts a Unicode string into an ANSI string.

takes a Unicode string, and returns an ANSI string. this is mainly needed for calls to NetApi32, which are Unicode only.

Parameters:
psz   a standard NULL terminated Unicode string
Returns:
an ANSI char string, wrapped in a std::auto_ptr, which will free the string memory when it goes out of scope

Definition at line 30 of file strconv.cpp.

00031 {
00032     int cb = WideCharToMultiByte ( CP_ACP, 0, psz, -1, NULL, 0, NULL, NULL ) ;
00033     std::auto_ptr<char> szdest ( new char[cb] ) ;
00034     WideCharToMultiByte ( CP_ACP, 0 , psz, -1, szdest.get(), cb, NULL, NULL ) ;
00035     return szdest ;
00036 }

fkostream& operator<< ( fkostream & o,
const token_group & g )
 

fkostream& operator<< ( fkostream & o,
const token & t )
 

fkostream& operator<< ( fkostream & o,
const GUID & g )
 

GUID inserter.

fkostream & fksec::operator<< ( fkostream & o,
const sid & s )
 

Inserts a textual representation, suitable for debugging, into an output stream.

Note that fkostream is a typedef for either std::ostream or std::wostream, depending on the UNICODE setting.

Parameters:
o   a reference to an ostream or wostream to insert the sid into
s   a reference to a sid to insert
Returns:
the stream reference o
Exceptions:
none  

Definition at line 1149 of file sid.cpp.

01150 {
01151     fkstr name, domain;
01152     SID_NAME_USE snu;
01153 
01154     o << _T( "[" ) + s.ConvertToStringSid() + _T( "]" );
01155 
01156     try { s.LookupSid( 0, name, domain, snu ); }
01157     catch ( ex *e )
01158     {
01159         // this didn't work too well. Don't display names, then.
01160         domain.erase();
01161         name.erase();
01162         delete e;
01163     }
01164 
01165     if ( ! domain.empty() || ! name.empty() )
01166     {
01167         o << _T( " (" );
01168         if ( ! domain.empty() )
01169             o << domain << _T( "\\" );
01170         o << name << _T( ", " ) << s.SnuToText( snu ) << _T( ")" );
01171     }
01172 
01173     return o;
01174 }

fkostream & fksec::operator<< ( fkostream & o,
const sd & s )
 

Definition at line 598 of file sd.cpp.

00599 {
00600     o << _T( "SD, control = " ) << s.GetControl() << std::endl;
00601 
00602     o << _T( "  " );
00603     o << ( s.haveOwnerSid? _T( "has" ): _T( "no" ) ) << _T( " owner, " );
00604     o << ( s.haveGroupSid? _T( "has" ): _T( "no" ) ) << _T( " group, " );
00605     o << ( s.haveDacl? _T( "has" ): _T( "no" ) ) <<
00606         ( s.protectedDacl? _T( "protected " ): _T( "" ) ) << _T( " DACL, " );
00607     o << ( s.haveSacl? _T( "has" ): _T( "no" ) ) <<
00608         ( s.protectedSacl? _T( "protected " ): _T( "" ) ) << _T( " SACL" );
00609     o << std::endl;
00610 
00611     if ( s.haveOwnerSid )
00612         o << _T( "Owner: " ) << s.ownerSid << std::endl;
00613 
00614     if ( s.haveGroupSid )
00615         o << _T( "Group: " ) << s.groupSid << std::endl;
00616 
00617     if ( s.haveDacl )
00618         o << ( s.protectedDacl? _T( "Protected " ): _T( "" ) ) << _T( "DACL: " ) << s.dacl;
00619 
00620     if ( s.haveSacl )
00621         o << ( s.protectedSacl? _T( "Protected " ): _T( "" ) ) << _T( "SACL: " ) << s.sacl;
00622 
00623     o << std::endl;
00624 
00625     return o;
00626 }

fkostream & fksec::operator<< ( fkostream & o,
const priv & p )
 

dumps interesting factoids about a priv instance into an ostream or wostream.

Parameters:
o   the ostream or wostream to insert the priv instance into
p   the priv instance to dump
Returns:
a reference to the ostream, as usual for inserters
Exceptions:
none  

Definition at line 140 of file priv.cpp.

00141 {
00142     bool state, haveState;
00143 
00144     try { state = p.GetState(); haveState = true; }
00145     catch ( ex & ) { haveState = false; }
00146 
00147     o << _T( "Privilege: " ) << p.privNum.LowPart << _T( ", " ) <<
00148         p.privName << _T( " (" ) << p.dispName << _T( ")" );
00149     if ( haveState )
00150         o << _T( ", state: " ) << ( state? _T( "enabled" ): _T( "disabled" ) );
00151     return o;
00152 }

fkostream & fksec::operator<< ( fkostream & o,
const ex & e )
 

dumps this exception to a stream.

An fkostream is a synonym for a std::ostream or a std::wostream, depending on the Unicode settings. operator<< writes a human-readable representation of the exception to such a stream, useful for diagnostics. Note that the output takes multiple lines and ends with a newline.

Parameters:
o   the ostream or wostream to write to
e   the exception to dump
Returns:
the fkostream reference that was passed in, as usual for inserters.
Exceptions:
unpredictable   depends on the iostreams library.

Definition at line 147 of file ex.cpp.

00148 {
00149     int i;
00150 
00151     o << _T( "exception: " ) << e.GetErr() << _T( ", " ) <<
00152         e.GetErrString() << _T( " (Win32: " ) << e.GetErrWin32() <<
00153         _T( ", data: " ) << e.GetData() << _T( ")" ) << std::endl;
00154 
00155     o << _T( "hop line source-file" ) << std::endl << _T( "         message" ) << std::endl;
00156 
00157     for ( i = 0; i < e.GetHopCount(); ++ i )
00158         o << std::setw( 3 ) << i << _T( " " ) << std::setw( 4 ) <<
00159             e[i].line << _T( " " ) << e[i].file << std::endl <<
00160             _T( "         " ) << e[i].msg << std::endl;
00161 
00162     if ( e.GetErrWin32() )
00163         o << e.GetWin32Desc() << std::endl;
00164     return o;
00165 }

fkostream & fksec::operator<< ( fkostream & o,
const acl & a )
 

dumps *this.

Inserts a in reasonably human-readable form into the output stream o. Note that fksec requires the use of the newer headers from the C++ Standard Library -- <iostream> instead of <iostream.h>.

Parameters:
o   a reference to an fkostream (resolving to either std::ostream or std::wostream, depending on the ambient character size) to which the acl is written
a   a const reference to the acl object to insert into the output stream
Returns:
a reference to the stream passed as the argument o
Exceptions:
none  

Definition at line 632 of file acl.cpp.

00633 {
00634     o << _T( "acl, " ) << a.aces.size() << _T( " ACEs, " )
00635         << a.additionalBytes << _T( " bytes extra space" ) << std::endl;
00636 
00637     for ( AceListConstIter i = a.aces.begin(); i != a.aces.end(); ++ i )
00638         o << _T( "  " ) << (*i) << std::endl;
00639 
00640     return o;
00641 }

fkostream & fksec::operator<< ( fksec::fkostream & o,
const ace & t )
 

GUID inserter.

Parameters:
o   a reference to a stream derived from std::ostream or std::wostream, depending on the UNICODE setting
a   the ACE to dump
Returns:
a reference to the fkostream that was passed in
Exceptions:
none  

Definition at line 649 of file ace.cpp.

00650 {
00651     o << _T( "ace: type " );
00652  
00653     if ( a.haveAceType )
00654         o << _T( "0x" ) << std::hex << std::setfill( _T( '0' ) ) << std::setw( 2 ) << (int) a.aceType << std::dec << std::setfill( _T( ' ' ) );
00655     else
00656         o << _T( "-NA-" );
00657 
00658     o << _T( ", flags: " );
00659     if ( a.haveAceFlags )
00660         o << _T( "0x" ) << std::hex << std::setfill( _T( '0' ) ) << std::setw( 2 ) << ( a.aceFlags & 0xff ) << std::dec << std::setfill( _T( ' ' ) );
00661     else
00662         o << _T( "-NA-" );
00663 
00664     o << _T( ", inheritance: " );
00665     if ( a.haveAceInheritance )
00666         o << _T( "0x" ) << std::hex << std::setfill( _T( '0' ) ) << std::setw( 2 ) << ( a.aceInheritance & 0xff ) << std::dec << std::setfill( _T( ' ' ) );
00667     else
00668         o << _T( "-NA-" );
00669 
00670     o << _T( ", mask: " );
00671     if ( a.haveAceMask )
00672         // with printf, this would be: printf( "0x%08lX", aceMask );
00673         // Brave New World of C++! This stream stuff deserves retroactive abortion.
00674         o << _T( "0x" ) << std::hex << std::setfill( _T( '0' ) ) << std::setw( 8 ) << a.aceMask << std::dec << std::setfill( _T( ' ' ) );
00675     else
00676         o << _T( "----NA----" );
00677 
00678     if ( a.IsObjectACE() )
00679     {
00680         o << _T( ", objectFlags: 0x" ) << std::hex << std::setfill( _T( '0' ) ) << std::setw( 2 ) << a.aceObjectFlags << std::dec << std::setfill( _T( ' ' ) ) ;
00681 
00682         o << _T(", objectType: " ) ;
00683         if ( a.aceObjectFlags & ACE_OBJECT_TYPE_PRESENT )
00684             o << a.aceObjectTypeGUID ;
00685         else
00686             o << _T( "-NA-" ) ;
00687 
00688         o << _T(", inheritedType: " ) ;
00689         if ( a.aceObjectFlags & ACE_INHERITED_OBJECT_TYPE_PRESENT )
00690             o << a.aceInheritedObjectTypeGUID ;
00691         else
00692             o << _T( "-NA-" ) ;
00693     }
00694 
00695     o << _T( ", sid: " );
00696     if ( a.aceSid.IsValid() )
00697         o << a.aceSid;
00698     else
00699         o << _T( "-none-" );
00700 
00701     return o;
00702 }

Variable Documentation

const int fksec::initialBufferSize = 2048 [static]
 

Definition at line 25 of file apis.cpp.

Generated at Mon Oct 16 06:14:25 2000 for fksec by doxygen1.2.2 written by Dimitri van Heesch, © 1997-2000