Use these members

• class TJwSecurityID in unit JwsclSid
• function JwSecurityCurrentThreadUserSID in unit JwsclKnownSID

The SID is either obtained from the thread token or – if it does not exist – from the process token.

Tell me how you liked this blog entry by adding a comment.

A principal is not recognized by its name, but by its unique SID which is a dynamic structure in the C world. It is made of three parts:

• A revision level that defines the sid version and currently is set to one (1).
• A 48 bit number which defines the authority that created the SID. (e.g. Windows NT defines 5)
• An array of numbers which uniquely identify the principal within the authority. The last number is sometimes called a relative identifier (RID).

A template string of a SID may look like this. (Brackets [ ] define optional parameters):

S – R – I [- S1 [- ... - Sn - [RID]]]

• S declares the string as a SID.
• R defines the revision number.
• S1-…-Sn defines the sub-authority. It is an array of n numbers that identifies a domain or machine.
• RID is the relative principal identifier. It is an unique, sequential and increasing number for a principal assigned by the authority. In Windows, known RIDs start with 500 which defines the Administrator account. RIDs of 1000 and above are used for the usual users and groups. The RID is not an independant part of a SID. In fact it is really the last part of the sub-authority array. Thus the Windows API and JWSCL do not have functions to read or alter it directly. To do so you must access the sub-authority array.

Windows defines some well known SIDs and some well known RIDs. Well knowns SIDs look the same on every computer because they have no domain or machine identifier. On the other hand there are well known RIDs which are system or domain relative. I write system as in operating system, because even on a multi boot computer the SIDs vary between different operating systems if they are not cloned. Several identical SIDs on different machines may lead to security problems. In this case there is a little helper called NewSID that helps changing the SID.

You can find a list of well known SIDs and RIDs in MSDN. Some important well known SIDs are shown here:

• S-1-1-0 : The Everyone group
• S-1-5-4 : The Interactive identifier which allows interactive logon.
• S-1-5-5-#-# : The Session Logon SID (more about it here ) “#” is a placeholder for the high and low value of the logon session ID called LUID. It can be retrieved from the principal’s token.

Here are some important well known RIDs. The ellipsis <…> represent the system or domain.

• S-1-5-<…>-500 : The Administrator account
• S-1-5-<…>-501 : The Guest account
• S-1-5-32 : The Builtin Local groups which identifies a member of a Builtin database

Some well known RIDs are appended to the Builtin SID to define them as special accounts and that they are hard-coded into the system.

• S-1-5-32-544 : The Administrators group
• S-1-5-32-545 : The Users group
• S-1-5-32-546 : The Guest group

1. Create a copy of an existing TJwSecurityID instance
2. Create a copy of an existing SID structure
3. Create a copy from a nested SID structure within a SidAndAttributes structure
4. Create a SID from an authority and an identifier
5. Create a well known SID from known constants
6. Create a SID from a string that represents the SID
7. Create a SID from the combination of a system and user name

These ways are accomplished by the TJwSecurity constructors:

1. constructor <strong>Create</strong>(const SecurityID: TJwSecurityId);
2. constructor <strong>Create</strong>(const SID: PSID);
3. constructor <strong>Create</strong>(const SID: PSidAndAttributes);

4. constructor <strong>Create</strong>(const Authorities: TJwSubAuthorityArray; Identifier: TSidIdentifierAuthority);
   

   constructor <strong>Create</strong>(const Authorities: array of Cardinal; Identifier: TSidIdentifierAuthority);
5. constructor <strong>CreateWellKnownSid</strong>(WellKnownSidType: TWellKnownSidType; DomainSid: TJwSecurityId = nil);
6. constructor <strong>Create</strong>(const SIDString: TJwString);
7. constructor <strong>Create</strong>(const SystemName, AccountName: TJwString);

1.

<u><strong>Create</strong>(const SecurityID: TJwSecurityId)</u>

2./3. <strong>Create</strong>(const SID: PSID)/<strong>Create</strong>(const SID: PSidAndAttributes);
It is quite uncommon to create an instance by using a SID structure. However if you ever encounter such a task you must be aware that the assigned SID is copied (not refered to it) into the instance. The const key-word in front of the parameter name denotes that parameter SID will not be altered internally. Thus there is no other way than to copy it. Also be aware that the SID memory is checked for a correct SID structure; otherwise EJwsclInvalidSIDException will be raised.

4. <strong>Create</strong>(const Authorities: TJwSubAuthorityArray; Identifier: TSidIdentifierAuthority);
It is easily possible to create a SID from scratch by using the internal parts of a SID. In the following example we create the well known group SID “Everybody”.

The constant five bytes long array identifier SECURITY_WORLD_SID_AUTHORITY from JwaWindows is declared as follow:

We add a subauthority of zero and get the shown output. The emtpy brackets usually contains the SID’s attributes which we did not use.

Everybody (S-1-1-0) []

The second constructors receives an declared array which describes the sub-authoroties. With the help of it we can alter an existing instance. The example shown below demonstrates how to alter the Everybody group by changing the sub authority array.

5. <strong>CreateWellKnownSid</strong>(WellKnownSidType: TWellKnownSidType;...);
The way to create a well known SID as shown in part #4 is very inconvenient. Thus the class TJwSecurityID contains a constructor that directly allows us to use one of the well known SID constants declared in JwaWindows or JwaVista (only if you need the new Vista definitions). The enumeration type WELL_KNOWN_SID_TYPE holds all known SIDs.

The CreateWellKnownSid constructor uses the definition from JwaVista. So if you do not use JwaVista in your use clause you have to add it now because the constructor uses the new version. In this case you should add JwaVista in front of JwaWindows since Delphi uses by default an identifier that is declared in the latest included unit.
The code below uses declarations introduced by JwaWindows but not JwaVista.

Of course it is possible to explicitly refer to JwaVista. This task is done by adding the unit name in front of the identifier seperated by a point operator.

Creating a well known SID in this way needs getting used to:

If you start programming and want to use Vista stuff from the beginning, you should add JwaVista after JwaWindows. In this case you can easily create a well known SID.

6. <strong>Create</strong>(const SIDString: TJwString);

A very convenient way to create a SID instance is to use the SID string format that was described at the very first part of this discussion.

Be warned that the constructor may raise an exception if you do not comply with the SID string format.

7. <strong>Create</strong>(const SystemName, AccountName: TJwString);

There is sometimes the necessity to get the SID of a user on a specific system. E.g. the user enters his name and the domain or machine name, in this case you can create a SID by a principal’s name. The following example creates a SID instance from the given user on the local system.

Call this method if you need display information of the SID instance. It shows information about the domain and user name, the SID string and attributes if any. Set the parameter ignoreExceptions to false if you want to get an exception if a SID could not be translated into an name. Set it to true if you just want an empty string to be displayed instead. If you don’t want to use too many exception handling mechanisms, you should set the parameter value to true.

Everybody (S-1-1-0) []

I already used this method to show you the output earlier in this article.

GetText uses the system or domain name once assigned to the constructor. However sometimes it is necessary to change it. The property CachedSystemName gets or sets this system or domain name.

This readonly property contains the SID’s string representation as shown in GetText.

Use the WellKnownSidType property if you need to know of what well known type the SID consists of. Be aware that you should not rely on it if the return value is WinNullSid, because in this case the SID could also be any other SID. The property returns this value for a NULL SID and also for a unknown SID. Use the boolean property IsWellKnownSID to check for a well known SID.

The attributes assigned to a SID can be used in different ways. Some WinAPI functions need them for example. However you can use two versions that are nearly equal. Either you set a bitmask using the property Attributes or you use a enumeration set with AttributesType.

Next time I’ll talk about more JWSCL classes that represent well known SIDs and are defined in the unit JwsclKnownSID.

Tell me how you liked this blog entry by adding a comment.

However sometimes we want to use our own security configuration to allow other participants to access a resource we created. JWSCL makes this task much more simple than using the security runtime function written in plain C. We do not have to create the security descriptor from scratch. The JWSCL methods allow us to get the default security descriptor and adapt it to our needs.

Let’s start with the required classes and methods we need to add another user who wants access.

• TJwSecurityDescriptor in unit JwsclDescriptor
• TJwDAccessControlList in unit JwsclAcl
• TJwDiscretionaryAccessControlEntryAllow in unit JwsclAcl
• TJwSecurityID in unit JwsclSid

That’s all.

Since the system already creates us an adequate security access list we want to continue using it. For this reason TJwSecurityDescriptor implements a constructor called CreateDefaultByToken that creates such a security access list automatically.

The output may look like this, depending on your Windows system.

Owner: chris@ Christian (S-1-5-21-2735234258-346234578-4357623456-1000) []
Group: chris@ None (S-1-5-21-2735234258-346234578-4357623456-513) [sidaGroupMandatory]
DACL:
ACE Count: 3
\#0
ClassName: TJwDiscretionaryAccessControlEntryAllow
AceType: Allow
Flags:
Accessmask: No map class given. 268435456, 0×10000000
SID: chris@ Christian (S-1-5-21-2735234258-346234578-4357623456-1000) []
#1
ClassName: TJwDiscretionaryAccessControlEntryAllow
AceType: Allow
Flags:
Accessmask: No map class given. 268435456, 0×10000000
SID: NT-AUTORIT-T@ SYSTEM (S-1-5-18) []
#2
ClassName: TJwDiscretionaryAccessControlEntryAllow
AceType: Allow
Flags:
Accessmask: No map class given. 2684354560, 0xA0000000
SID: (S-1-5-5-0-151391) []

SACL:
ACE Count: 0
\

(No map class given is shown because the security descriptor class does not know the type of secured object. A map class (derived from TJwSecurityGenericMapping) can convert the AccessMask to an human readable string)

The system sets the owner to the current token owner of the process or thread. It also adds my user account and the SYSTEM principal with full access (0×10000000 = GENERIC_ALL). The unknown principal with the Sid S-1-5-5-0-151391 describes the loggon session Sid. At a later point we will remove it.
For the discussion we want to add another principal called Alice so she can get read access to the file/folder. Because we need the Alice’s Sid we have to add another variable called AliceSid.

In the code above a new class instance of TJwDiscretionaryAccessControlEntryAllow is added to the DACL. Because we create just a simple file we do not need special flags thus an empty flag set [] is applied. The access mask parameter will receive GENERIC_READ as the maximum possible access to this file granted to Alice. The last parameter (OwnSid) is set to true and defines that the access control list (here property DACL) destroys the instance AliceSid at the end.

The resulting security descriptor has now a new access control entry. The output is the same like above but with this additional element.

ClassName: TJwDiscretionaryAccessControlEntryAllow
AceType: Allow
Flags:
Accessmask: No map class given. 2147483648, 0×80000000
SID: chris@ Alice (S-1-5-21-2735234258-346234578-4357623456-1008) []

Now we can arrive at the part where CreateFile comes in. How can we create a pointer to a TSecurityAttribute type? It is really simple! We just have to declare some more helper variables that CreateFile needs and use Create_SA.

Create_SA from TJwSecurityDescriptor creates the necessary memory structure (SecurityAttributes) and returns a pointer of type PSecurityAttributes. The pointer is used in CreateFile to apply our own security descriptor. Our access control list of the newly created file will contain all the elements you see above as output. In tests, both the creation flags CREATE_NEW and CREATE_ALWAYS never change the security attributes after the file has already been created. Although MSDN explains it correctly for CREATE_ALWAYS it does not say anything about CREATE_NEW in this context. Because of this we simply delete the file everytime.

The security editor of Windows Explorer shows us the new descriptor.

As you can see we did not remove the LogonSession Sid from the security descriptor. The logon SID resides in the principal’s token. It is used to add allow or deny access to a secured object but only for the time the user is logged on. This is because every time the user logs on, a new session Sid is generated. Additionally all calls to the LogonUser API get their own session Sid so a logon Sid is a fine grained access control that allows us not only to restrict access between users but also control access between several different instances of a user (consider the user itself as a class and all user tokens as instances of this class) .
However removing this LogonSID will be our next task because we do not need it here.

JWSCL supports us with a function that returns a TJwSecurityId of the logon session. The function is called JwGetLogonSID and resides in unit JwsclKnownSid that we have to include additionally. Unfortunately there is a bug in revision 316 that makes it impossible to use it. For this reason I added an adapted version of the whole unit JwsclKnownSid . You can get it here.

Let’s see how we can get rid of the logon sid.

JwGetLogonSid returns a new instance that can be used to search for the logon Sid in the DACL. The method FindSID in TJwDAccessControlList goes through the whole access control list and returns the zero based index of the entry we search for. If it were not to be found we would get a negative result value, but this is not the case here (although we check for it because it is good programming style). At the end do not forget to remove the instance.

The new security descriptor does not contain the annoying logon Sid anymore. Eventually we can use this discussed approach not only for CreateFile but also for CreatePipe, CreateProcess, RegCreateKeyEx, RegSaveKeyEx, CreateFileMapping and many more. I used CreateFile so you can easily look up the descriptor in the security editor of Windows Explorer.

The next article will discuss how we can use inheritance and why there are no inherited access control elements in our created security descriptor although the parent folder hand them down.

Tell me how you liked this blog entry by adding a comment.

Both tokens are linked together. Thus the following conditions are true.

Token.LinkedToken = TwinToken
TwinToken.LinkedToken = Token

You can use the twin token in any way you treat a token if you are powerful enough. Use it in CreateProcess or impersonate the user to do things as the user.

At the end I post a quite useful piece of code that displays primary information about a token.

Tell me how you liked this blog entry by adding a comment.