The following code creates a folder named “JWSCLTest” and applies a DACL that allows full control to everyone. The folder will inherit its security settings to child folders and files (check the afXXX flags).

const JWSCLTestFolder = 'JWSCLTestFolder';

var
  SD : TJwSecurityDescriptor;
  pSA : PSecurityAttributes;
begin
  JwInitWellKnownSIDs;

  SD := TJwSecurityDescriptor.Create;
  try
    SD.DACL.Add(TJwDiscretionaryAccessControlEntryAllow.Create(nil,
      [afContainerInheritAce, afObjectInheritAce], FILE_ALL_ACCESS, JwWorldSID));

    pSA := SD.Create_SA();
    try
      Win32Check(CreateDirectory(JWSCLTestFolder, pSA));
    finally
      SD.Free_SA(pSA); //remember to free pointer
    end;
  finally
    SD.Free;
  end;
end.

CreateDirectory receives a security attributes structure that is applied to the folder directly. However, in this way the parent security descriptor is not inherited to our folder. This is called a protected DACL because the inheritance flow is stopped. So we get a folder with only one Access Control Entry (ACE) : Everyone (aka World SID). To remedy that we can copy the ACEs from the parent folder to our own folder:

procedure MergeParentDACL(const Location : String; TargetSD : TJwSecurityDescriptor);
var DirSD : TJwSecureFileObject;
begin
  DirSD := TJwSecureFileObject.Create(Location);
  try
    TargetSD.DACL.AddACEs(DirSD.DACL);
  finally
    DirSD.Free;
  end;
end;

var
  DirSD : TJwSecureFileObject;

  SD, SD2 : TJwSecurityDescriptor;
  pSA : PSecurityAttributes;
begin
  JwInitWellKnownSIDs;

  SD := TJwSecurityDescriptor.Create;

  try
    SD.DACL.Add(TJwDiscretionaryAccessControlEntryAllow.Create(nil,
      [afContainerInheritAce, afObjectInheritAce], FILE_ALL_ACCESS, JwWorldSID));

    MergeParentDACL('.', SD);

    pSA := SD.Create_SA();
    try
      Win32Check(CreateDirectory(JWSCLTestFolder, pSA));
    finally
      SD.Free_SA(pSA);
    end;
  finally
    SD.Free;
  end;
end.

The function MergeParentDACL receives the location of the parent folder and retrieves its security settings. Then its DACL is copied to the target security descriptor. JWSCL with TargetSD.DACL.AddACEs makes sure that the order of the ACEs are still correct (first deny then allow entries) by moving them accordingly.

In addition, there is a second, much easier way to achieve the same result.

var
  SD : TJwSecurityDescriptor;
  DirSD : TJwSecureFileObject;
begin
  JwInitWellKnownSIDs;

  Win32Check(CreateDirectory(JWSCLTestFolder, nil));

  DirSD := TJwSecureFileObject.Create(JWSCLTestFolder);
  try
    SD := DirSD.GetSecurityDescriptor([siDaclSecurityInformation]);
    try
      SD.DACL.Add(TJwDiscretionaryAccessControlEntryAllow.Create(nil,
        [afContainerInheritAce, afObjectInheritAce], FILE_ALL_ACCESS, JwWorldSID));

      DirSD.SetSecurityDescriptor(SD, [siDaclSecurityInformation]);
    finally
      SD.Free;
    end;
  finally
    DirSD.Free;
  end;

In this way we didn’t set the security descriptor directly when the folder was created. Nevertheless we get a combination of inheritace ACEs plus the explicit one (JwWorldSID).

Note

It is always a good idea to check whether SD.DACL (in above codes) is nil and if so ignore it or create a new and empty one to be used instead. It is always possible that a file or folder comes with a nil DACL which means either no access at all (flag DACLpresent) or everyone has full access (flag DACLpresent not available).

I used the following JEDI units:

uses
  JwaWindows,

  JwsclDescriptor,
  JwsclTypes,
  JwsclConstants,
  JwsclKnownSid,
  JwsclAcl,
  JwsclMapping,
  JwsclSecureObjects,
  JwsclSid,

The ACTRL_ACCESS structure is used by the interface method IAccessControl::GetAllAccessRights (and others) which is rather hard to implement yourself because the structure must be created in a single block of memory that can be freed by CoTaskMemFree.

So here is how it looks like

ACTRL_ACCESS design diagram

Luckily, JWSCL will provide an implementation of IAccessControl so don’t worry.

The following code will also be available in the example section of the source code. The application gets a file or folder name as parameter and tries to add the user with full access control. It even tries to get ownership if it can’t change the access control list.

First of all we need some JWSCL classes:

• TJwSecurityDescriptor
  A security descriptor contains all information about security of an object. It contains the owner and the access control list (also some other thing, we don’t need here)
• TJwSecureFileObject
  This class provides methods to read and write security information on a file or folder. Despite its name it does also support folders. It even supports inheritance.
  You can access a file or folder through its name, a handle or the VCL class TFileStream.
• TJwDAccessControlList
  This class contains methods to maintain a discreationary access control list (DACL). A DACL contains a list of users and their possible access on the object.
• TJwSecurityId
  Every user is identified by a unique number which is maintained by this class.
• TJwSecurityToken
  Every logged on user gets a security pass which contains information what she can do or not. We mainly use it to retrieve the user’s SID (TJwSecurityID)

These classes are stored in the JWSCL units. We use the following ones:

The units above are necessary and contain all the classes described earlier Of course we have to declare the classes:

This example also shows how we can add well known Security Identifiers (SID) to a secured object. We have to initialize them. The variable JwWorldSID will then contain the correct SID for group Everyone. If we didn’t call it, we would get nil instead.
JwInitWellKnownSIDs;

The next steps are creating the classes. We get the user name through her token and save the SID into Owner.
Later we will use the Owner instance to add it into the security information of the object.

The actual class which does all the work on the file/folder is TJwSecureFileObject. We just apply the first parameter.

Notice: A user can only change security information of an object if she has the right to do it. There are two options to allow it.

1. The user is listed in the DACL. Additionally the right WRITE_DAC is granted for her.
2. The user is the owner. In this case she don’t need to be listed and allowed in the DACL. It is automatically granted

We can check both version in one call.

This call is very easy. If we can’t change the DACL, we can try to become the owner. The only way to become an owner is to enable a privilege called SE_TAKE_OWNERSHIP_NAME. It is usually only granted to Administrators.

JwEnablePrivilege will fail, if it can’t activate the privilege. Otherwise we can set the file/folder’s owner to the token user.

The main work is done here. We get the default DACL from the existing object and adapt it.

Adaption is done by adding the user to the DACL with full control. We additionally allow the Everyone group to demonstrate the well known Sids initialized by JwInitWellKnownSIDs. The last parameters (false) define that we don’t want the list to free the given SIDs (Owner and JwWorldSid) automatically.

And finally we reset the DACL.

The DACL of the file or folder will receive the newly created control entries in addition to its existing ones. If it contains inherited entries (entries from a parent folder) they will be conserved. However if you don’t retrieve the DACL and just use an empty one, all previously existing entries which are not inherited will be removed. Of course the inherited entries will still remain intact.

And of course we free all allocated resources

Since I cut the source code into pieces, I’ll show it here in full glory

1. explicit Deny elements
2. explicit Allow elements
3. inherited Deny elements
4. inherited Deny elements

It is also called the canonical order.

Any order that doesn’t follow the semantic above, hasn’t got to be wrong. In fact you can define an order that solves your situation (some MS software does). But you shouldn’t do this where a user can find and edit it (like regkeys and files), otherwise the security descriptor editor in Windows Explorer and registry editor will show you a nasty warning. Moreover if you mix them up, the result of an AccessCheck may be difficult to understand for the user (bad user experience). And eventually, the unusual order could also create a security risk because a user could access a resource although it is explicitly denied. It happens when the user is (accidentally) granted access by placing an allow ACE in front of a deny ACE and both ACEs pointing to the same SID. The reason comes from the fact that an access check iterates through the (linear) access control list and stops when the first SID was found. So the first SID wins and defines whether access is granted or denied.

• TJwDiscretionaryAccessControlEntryDeny
  TJwDiscretionaryAccessControlEntryAllow in unit JwsclAcl
• TJwSecurityDescriptor in unit JwsclDescriptor

The result can be seen here:

1. deny explicit Sid2
2. allow explicit Sid1
3. deny inherited Sid4
4. allow inherited Sid3

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.