/*++ Copyright (c) 1989 Microsoft Corporation Module Name: tokenp.h Abstract: This module contains the internal (private) declarations needed by the TOKEN object routines. It also contains global variables needed by the TOKEN object routines. Author: Jim Kelly (JimK) 18-May-1990 Revision History: v10: robertre Added SepAccessCheck and SepPrivilegeCheck prototypes v11: robertre Added parameter to SepAccessCheck --*/ #ifndef _TOKENP_ #define _TOKENP_ //#define TOKEN_DEBUG #include "ntos.h" #include "sep.h" #include "seopaque.h" ///////////////////////////////////////////////////////////////////////// // // // Token Diagnostics // // // ///////////////////////////////////////////////////////////////////////// #if DBG #define TOKEN_DIAGNOSTICS_ENABLED 1 #endif // DBG // // These definitions are useful diagnostics aids // #if TOKEN_DIAGNOSTICS_ENABLED // // Test for enabled diagnostic // #define IF_TOKEN_GLOBAL( FlagName ) \ if (TokenGlobalFlag & (TOKEN_DIAG_##FlagName)) // // Diagnostics print statement // #define TokenDiagPrint( FlagName, _Text_ ) \ IF_TOKEN_GLOBAL( FlagName ) \ DbgPrint _Text_ #else // !TOKEN_DIAGNOSTICS_ENABLED // // No diagnostics included in build // // // Test for diagnostics enabled // #define IF_TOKEN_GLOBAL( FlagName ) if (FALSE) // // Diagnostics print statement (expands to no-op) // #define TokenDiagPrint( FlagName, _Text_ ) ; #endif // TOKEN_DIAGNOSTICS_ENABLED // // The following flags enable or disable various diagnostic // capabilities within token code. These flags are set in // TokenGlobalFlag (only available within a DBG system). // // // TOKEN_LOCKS - Display information about acquisition and freeing // of token locks. // #define TOKEN_DIAG_TOKEN_LOCKS ((ULONG) 0x00000001L) ///////////////////////////////////////////////////////////////////////// // // // Token Related Constants // // // ///////////////////////////////////////////////////////////////////////// // // By default, a token is charged the following for its dynamic component. // The dynamic component houses the default ACL and primary group ID. // If the size of these parameters passed upon token creation are larger // than this default, then the larger value will be charged. // #define TOKEN_DEFAULT_DYNAMIC_CHARGE 500 ///////////////////////////////////////////////////////////////////////// // // // Token Object Body // // // ///////////////////////////////////////////////////////////////////////// // // Tokens have three parts: // // Fixed part of body, // Variable part of body, // Dynamic part (not in body). // // The fixed and variable parts are allocated in a single block of memory. // The dynamic part is a separately allocated block of memory. // // The fixed part of the body contains the fixed length fields. These // are defined in the TOKEN data type. // // The variable part of the body is variable in length and contains // privileges and user/group SIDs. This part is variable in length // between different token objects, but does not change once established // for an individual token. // // The dynamic part is used to house default discretionary ACL information // and the primary group ID. // // Pictorially, a token looks like: // // ============== +---------------+ // ^ | | // | | | // | | | // | | DynamicPart o-----------+ // | |- - - - - - - -| | // +-----o Privileges | | // Token | |- - - - - - - -| | // Body | +--o UserAndGroups | \|/ // | | |- - - - - - - -| +---------------------+ // | | | | PrimaryGroup o------->| [Primary Group SID] | // | | | |- - - - - - - -| | o | // | | | | DefaultAcl o---+ | o | // | | | |- - - - - - - -| | | o | // | | | | o | | |- - - - - - - - - - -| // | | | | o | +--->| [ Default Acl ] | // v | | | o | | o | // ==============| | |===============| | o | // ^ | +->| SIDs Array | | o | // | | | [User SID ] | +---------------------+ // | | | [Group SID ] | // | | [Group SID ] | // Variable | | o | // Part | | o | // | |- - - - - - - -| // | +---->| Privileges | // | | Array | // v | | // ============== +---------------+ // // WARNING: The positions of fields illustrated in this picture are not // intented to reflect their actual or even relative positions // within the real data structures. The exception to this is // that THE USER SID IS THE FIRST SID IN THE UserAndGroups // ARRAY. // // // ! ! ! ! IMPORTANT ! ! ! ! // // The access validation routines assume the SIDs are arranged // in a particular order within the variable part of the token. // Any changes to the order of the SIDs must be coordinated with // corresponding changes to the access validation routines. // // ! ! ! ! ! ! ! ! ! ! ! typedef struct _TOKEN { // // Fields arranged by size to preserve alignment. // Large fields before small fields. // // // The following fields are either ReadOnly or ReadWrite. // ReadOnly fields may be referenced any time a pointer to the // token is still valid. ReadWrite fields may only be referenced // when the TokenLock is held. // The dynamic part of the token (pointed to by the DynamicPart field) // is also protected by the token lock. // // ReadOnly fields are marked Ro: in their comment. // ReadWrite fields are marked Wr: in their comment. // TOKEN_SOURCE TokenSource; // Ro: 16-Bytes LUID TokenId; // Ro: 8-Bytes LUID AuthenticationId; // Ro: 8-Bytes LARGE_INTEGER ExpirationTime; // Ro: 8-Bytes // // Each time the security information in a token is changed, the // following ID is changed. Fields that cause this field to be // updated are marked as (Mod) in their comment field. // LUID ModifiedId; // Wr: 8-Bytes ULONG UserAndGroupCount; // Ro: 4-Bytes ULONG PrivilegeCount; // Ro: 4-Bytes ULONG VariableLength; // Ro: 4-Bytes ULONG DynamicCharged; // Ro: 4-Bytes ULONG DynamicAvailable; // Wr: 4-Bytes (Mod) ULONG DefaultOwnerIndex; // Wr: 4-Bytes (Mod) PSID_AND_ATTRIBUTES UserAndGroups; // Wr: 4-Bytes (Mod) PSID PrimaryGroup; // Wr: 4-Bytes (Mod) PLUID_AND_ATTRIBUTES Privileges; // Wr: 4-Bytes (Mod) PULONG DynamicPart; // Wr: 4-Bytes (Mod) PACL DefaultDacl; // Wr: 4-Bytes (Mod) TOKEN_TYPE TokenType; // Ro: 1-Byte SECURITY_IMPERSONATION_LEVEL ImpersonationLevel; // Ro: 1-Byte UCHAR TokenFlags; // Ro: 4-Bytes BOOLEAN TokenInUse; // Wr: 1-Byte PSECURITY_TOKEN_PROXY_DATA ProxyData; // Ro: 4-Bytes PSECURITY_TOKEN_AUDIT_DATA AuditData; // Ro: 4-Bytes // // This marks the beginning of the variable part of the token. // It must follow all other fields in the token. // ULONG VariablePart; // Wr: 4-Bytes (Mod) } TOKEN, * PTOKEN; // // Where: // // TokenSource - Information provided by the executive component that // requested the logon that the token represents. // // // TokenId - Is an LUID value. Each token object has a uniquely // assigned LUID. // // // AuthenticationId - Is the LUID assigned by the domain controller for // the logon session. // // // ExpirationTime - Not yet supported in NT. // // // ModifiedId - Is an LUID which is changed each time a modification is // made to this token which changes the security semantics of the // token. This includes enabling/disabling privileges and groups // and changing default ACLs, et cetera. Any token which is a // duplicate of this token will have the same ModifiedId (until // one or the other is changed). This does not cover changes to // non-security semantics fields, like TokenInUse. // // // UserAndGroupCount - Indicates the number of user/group IDs in this token. // This value must be at least 1. A value of 1 indicates a user // ID with no supplemental group IDs. A value of 5 indicates a // user ID and 4 supplemental group IDs. // // PrivilegeCount - Indicates how many privileges are included in // this token. May be zero or larger. // // TokenType - Indicates which type of token this token object is. // // ImpersonationLevel - For TokenImpersonation type tokens, this field // indicates the impersonation level. For TokenPrimary type tokens, // this field is ignored. // // DynamicCharged - Indicates how much pool quota has been charged // for the dynamic portion of this token. // // DynamicAvailable - Indicates how much of the charged quota is still // available for use. This is modified when pool associated // with the dynamic portion of the token is allocated or freed, // such as when the default DACL or primary group is replaced. // // // DefaultOwnerIndex - If non-zero, identifies an ID that has explicitly // been established as the default owner for this token. If it is zero, // the standard default (user ID) is used as the default owner. // // UserAndGroups - Points to an array of SID_AND_ATTRIBUTES. The first // element in this array is the token's user ID. Any additional // elements are those of groups. The number of entries in this // array is one greater than // // PrimaryGroup - Points to an SID that is to be used as the primary // group of the token. There are no value restrictions // placed upon what can be used as a primary group. This // SID is not one of user or group IDs (although it may have the // same value as one of those IDs). // // Privileges - Points to an array of privileges represented as // LUID_AND_ATTRIBUTES. The number of elements in this array // is contained in the PrivilegesCount field. // // TokenInUse - Is a boolean that indicates whether a primary token // is already in use by a process. This field value is only // valid for primary tokens. // // ProxyData - Optionally points to a Proxy data structure, containing // the information to be passed to AVR routines by file systems. // This field being non-null identifies the token as a proxy token. // // AuditData - Optionally points to an Audit data structure, containing // global auditing data for this subject. // // NOTE: Access to this field is guarded by the global // PROCESS SECURITY FIELDS LOCK. // VariablePart - Is the beginning of the variable part of the token. // ///////////////////////////////////////////////////////////////////////// // // // Token Specific Macros // // // ///////////////////////////////////////////////////////////////////////// #ifndef TOKEN_DIAGNOSTICS_ENABLED #define SepAcquireTokenReadLock(T) KeEnterCriticalRegion(); \ ExAcquireResourceShared(&SepTokenLock, TRUE) #define SepAcquireTokenWriteLock(T) KeEnterCriticalRegion(); \ ExAcquireResourceExclusive(&SepTokenLock, TRUE) #define SepReleaseTokenReadLock(T) ExReleaseResource(&SepTokenLock); \ KeLeaveCriticalRegion() #else // TOKEN_DIAGNOSTICS_ENABLED #define SepAcquireTokenReadLock(T) if (TokenGlobalFlag & TOKEN_DIAG_TOKEN_LOCKS) { \ DbgPrint("SE (Token): Acquiring Token READ Lock for access to token 0x%lx\n", (T)); \ } \ KeEnterCriticalRegion(); \ ExAcquireResourceShared(&SepTokenLock, TRUE) #define SepAcquireTokenWriteLock(T) if (TokenGlobalFlag & TOKEN_DIAG_TOKEN_LOCKS) { \ DbgPrint("SE (Token): Acquiring Token WRITE Lock for access to token 0x%lx ********************* EXCLUSIVE *****\n", (T)); \ } \ KeEnterCriticalRegion(); \ ExAcquireResourceExclusive(&SepTokenLock, TRUE) #define SepReleaseTokenReadLock(T) if (TokenGlobalFlag & TOKEN_DIAG_TOKEN_LOCKS) { \ DbgPrint("SE (Token): Releasing Token Lock for access to token 0x%lx\n", (T)); \ } \ ExReleaseResource(&SepTokenLock); \ KeLeaveCriticalRegion() #endif // TOKEN_DIAGNOSTICS_ENABLED #define SepReleaseTokenWriteLock(T,M) \ { \ if ((M)) { \ ExAllocateLocallyUniqueId( &((PTOKEN)(T))->ModifiedId ); \ } \ SepReleaseTokenReadLock( T ); \ } // // Reference individual privilege attribute flags of any privilege array // // P - is a pointer to an array of privileges (PLUID_AND_ATTRIBUTES) // I - is the index of the privilege // A - is the name of the attribute desired (e.g., Enabled, EnabledByDefault, etc. ) // #define SepArrayPrivilegeAttributes(P,I) ( (P)[I].Attributes ) // // Reference individual privilege attribute flags of token privileges // // T - is a pointer to a token // I - is the index of the privilege // A - is the name of the attribute desired (e.g., Enabled, EnabledByDefault, etc. ) // #define SepTokenPrivilegeAttributes(T,I) ( (T)->Privileges[I].Attributes ) // // Reference individual group attribute flags of any group array // // G - is a pointer to the array of groups (SID_AND_ATTRIBUTES[]) // I - is the index of the group // #define SepArrayGroupAttributes(G,I) ( (G)[I].Attributes ) // // Reference individual group attribute flags of token groups // // T - is a pointer to a token // I - is the index of the group // #define SepTokenGroupAttributes(T,I) ( (T)->UserAndGroups[I].Attributes ) //////////////////////////////////////////////////////////////////////// // // // Private Routine Declarations // // // //////////////////////////////////////////////////////////////////////// NTSTATUS SepAdjustGroups( IN PTOKEN Token, IN BOOLEAN MakeChanges, IN BOOLEAN ResetToDefault, IN ULONG GroupCount OPTIONAL, IN PSID_AND_ATTRIBUTES NewState OPTIONAL, OUT PTOKEN_GROUPS PreviousState OPTIONAL, OUT PSID SidBuffer OPTIONAL, OUT PULONG ReturnLength, OUT PULONG ChangeCount, OUT PBOOLEAN ChangesMade ); NTSTATUS SepAdjustPrivileges( IN PTOKEN Token, IN BOOLEAN MakeChanges, IN BOOLEAN DisableAllPrivileges, IN ULONG PrivilegeCount OPTIONAL, IN PLUID_AND_ATTRIBUTES NewState OPTIONAL, OUT PTOKEN_PRIVILEGES PreviousState OPTIONAL, OUT PULONG ReturnLength, OUT PULONG ChangeCount, OUT PBOOLEAN ChangesMade ); VOID SepAppendDefaultDacl( IN PTOKEN Token, IN PACL PAcl ); VOID SepAppendPrimaryGroup( IN PTOKEN Token, IN PSID PSid ); NTSTATUS SepDuplicateToken( IN PTOKEN ExistingToken, IN POBJECT_ATTRIBUTES ObjectAttributes, IN BOOLEAN EffectiveOnly, IN TOKEN_TYPE TokenType, IN SECURITY_IMPERSONATION_LEVEL ImpersonationLevel OPTIONAL, IN KPROCESSOR_MODE RequestorMode, OUT PTOKEN *DuplicateToken ); VOID SepFreeDefaultDacl( IN PTOKEN Token ); VOID SepFreePrimaryGroup( IN PTOKEN Token ); BOOLEAN SepIdAssignableAsOwner( IN PTOKEN Token, IN ULONG Index ); VOID SepMakeTokenEffectiveOnly( IN PTOKEN Token ); BOOLEAN SepTokenInitialization( VOID ); VOID SepTokenDeleteMethod ( IN PVOID Token ); // // These are here because if they are placed in sep.h, we don't // have the PTOKEN datatype available. // BOOLEAN SepPrivilegeCheck( IN PTOKEN Token, IN OUT PLUID_AND_ATTRIBUTES RequiredPrivileges, IN ULONG RequiredPrivilegeCount, IN ULONG PrivilegeSetControl, IN KPROCESSOR_MODE PreviousMode ); BOOLEAN SepAccessCheck ( IN PSECURITY_DESCRIPTOR SecurityDescriptor, IN PTOKEN PrimaryToken, IN PTOKEN ClientToken, IN ACCESS_MASK DesiredAccess, IN PGENERIC_MAPPING GenericMapping, IN ACCESS_MASK PreviouslyGrantedAccess, IN KPROCESSOR_MODE PreviousMode, OUT PACCESS_MASK GrantedAccess, OUT PPRIVILEGE_SET *Privileges OPTIONAL, OUT PNTSTATUS AccessStatus ); #ifdef TOKEN_DEBUG VOID SepDumpToken( IN PTOKEN T ); #endif //TOKEN_DEBUG //////////////////////////////////////////////////////////////////////// // // // Global Variables // // // //////////////////////////////////////////////////////////////////////// extern GENERIC_MAPPING SepTokenMapping; extern POBJECT_TYPE SepTokenObjectType; extern ERESOURCE SepTokenLock; #ifdef TOKEN_DIAGNOSTICS_ENABLED extern ULONG TokenGlobalFlag; #endif // TOKEN_DIAGNOSTICS_ENABLED #endif // _TOKENP_