The name of the API is IFileIsInUse, an interface. It resides in Shobjidl.h, Shobjidl.idl and newly in JwaShlObj.pas. This is the translation:

{$IFDEF WINVISTA_UP}
const
  IID_IFileIsInUse: TGUID = (
    D1:$64a1cbf0; D2:$3a1a; D3:$4461; D4:($91,$58,$37,$69,$69,$69,$39,$50));

type
  {$ALIGN 4}
  tagFILE_USAGE_TYPE = (
    FUT_PLAYING = 0,
    FUT_EDITING = 1,
    FUT_GENERIC = 2
  );
  FILE_USAGE_TYPE = tagFILE_USAGE_TYPE;
  TFileUsageType = FILE_USAGE_TYPE;

const
  OF_CAP_CANSWITCHTO     = $0001;
  OF_CAP_CANCLOSE        = $0002;

type
  IFileIsInUse = interface(IUnknown)
    ['{64a1cbf0-3a1a-4461-9158-376969693950}']
    function GetAppName(out ppszName: LPWSTR) : HRESULT; stdcall;
    function GetUsage(out pfut : FILE_USAGE_TYPE) : HRESULT; stdcall;
    function GetCapabilities(out pdwCapFlags : DWORD) : HRESULT; stdcall;
    function GetSwitchToHWND(out phwnd : HWND) : HRESULT; stdcall;
    function CloseFile() : HRESULT; stdcall;
  end;

{$ENDIF WINVISTA_UP}

The interface can be used as a client and also can be implemented by a server. A client usually checks if a file has a lock and retrieves a pointer to this interface to access the methods. A server usually holds a lock on a given file and implements the interface to provide the methods to the client. This article will discuss only the client side.
You see that this API only works if both sides do their jobs. A process that locks a file must also implement this interface and register it, so a client can receive a status information. There is no direct link between a file lock and the process name. If a process holds a lock on a file but does not implement the interface you are on your own again. 
Eventually, this is only a shell helper for the nice Windows Explorer deletion dialog.

  IFileIsInUse = interface(IUnknown)
    function GetAppName(out ppszName: LPWSTR) : HRESULT; stdcall;
    function GetUsage(out pfut : FILE_USAGE_TYPE) : HRESULT; stdcall;
    function GetCapabilities(out pdwCapFlags : DWORD) : HRESULT; stdcall;
    function GetSwitchToHWND(out phwnd : HWND) : HRESULT; stdcall;
    function CloseFile() : HRESULT; stdcall;
  end;

The methods of the interface are really easy to understand.

• GetAppName retrieves the name of the process that holds the file. It can be any chosen name by the application designer. To get the name use always a PWideChar and don’t forget to free it with CoTaskMemFree (it uses the interface IMalloc). Don’t forget to check for the result. If you like exception you can also rewrite the code using safecall (convert the function to a procedure then).
• GetUsage returns the reason why the file is locked. It can be one of the enumeration constant of  TFileUsage. Either it can be playing a video or music or editing a file. If these are not sufficient the value FUT_GENERIC must be used. Maybe there will be more values in future.
• GetCapabilities returns a set of flags in a DWORD. They define whether the file can be closed (OF_CAP_CANCLOSE) by calling CloseFile or the we can put the application into foreground (OF_CAP_CANSWITCHTO). Be aware that you should inform the user that you are about to switch the window. Otherwise she could get nervous about her missing application window. Switching the window can be done by SetForegroundWindow. But your application must have a focus (and some other rules, see MSDN SetForegroundWindow) to switch the window; otherwise nothing happens.
• GetSwitchToHWND returns a window handle of the other process. Only use this handle to switch to the window. You don’t really know what window is returned here. Don’t try to close it or anything else because this is just bad behaviour. At all costs, check the return value. Otherwise you don’t know whether the returned window handle is valid or just an random number. In worst case it is an existing window from your process. Well, COM rules tell us to nullify the out parameters but usually it is better to check.
  Of course, the call is only valid if GetCapabilities returns the bit OF_CAP_CANSWITCHTO.
• CloseFile implements the server side of closing the file. The call is only valid if GetCapabilities returns the bit OF_CAP_CANCLOSE. Well, this is really nice. However, don’t trust it! Always recheck the lock on the file instead of continuing blindly.

To retrieve an interface on the file you have to lock it first. Either you download and compile the MSDN example IsFileInUse or you open up an application that implements the interface (e.g. a PDF Reader, MS Office).

The next step is to know where the locked files are placed. The location is the running object table, short ROT (ActiveX.GetRunningObjectTable() retrieves it). It is a global* (on machine) table that holds running COM objects. You can implement your own interfaces and put it in this table. Because interfaces can be arbitrary in its structure and reason to be,  they are attached to monikers (IMoniker) which describe them uniquely. There are several types of monikers like class, item and file moniker (more information provides IMoniker in MSDN). We are interested in the latter only.
So the whole work is an enumeration over all monikers in the ROT.  Usually there are not that much in there (I got 5 here). Each moniker is checked for its type (IsSystemMoniker) and if it is a file moniker (MKSYS_FILEMONIKER) the path is compared to the input parameter FileName. Honestly, I cannot tell why there is a comparison of the prefix at first followed by a comparison of the moniker itself, sorry. 
The object itself is retrieved from the moniker by GetObject. It may fail with E_ACCESS_DENIED so a check is done using Succeeded. In the end, we can try to retrieve the IFileIsInUse interface. There may be such a file registered but without the implementation of the interface, thus an additional check.

I didn’t create this whole source by myself. In fact, there is a FileIsInUse example in MSDN that is the base of this article. The original source is located in the docx file in the download. The example FileIsInUse will create a server.

function GetFileInUseInfo(const FileName : WideString) : IFileIsInUse;
var
  ROT : IRunningObjectTable;
  mFile, enumIndex, Prefix : IMoniker;
  enumMoniker : IEnumMoniker;
  MonikerType : LongInt;
  unkInt  : IInterface;
begin
  result := nil;

  OleCheck(GetRunningObjectTable(0, ROT));
  OleCheck(CreateFileMoniker(PWideChar(FileName), mFile));

  OleCheck(ROT.EnumRunning(enumMoniker));

  while (enumMoniker.Next(1, enumIndex, nil) = S_OK) do
  begin
    OleCheck(enumIndex.IsSystemMoniker(MonikerType));
    if MonikerType = MKSYS_FILEMONIKER then
    begin
      if Succeeded(mFile.CommonPrefixWith(enumIndex, Prefix)) and
         (mFile.IsEqual(Prefix) = S_OK) then
      begin
       if Succeeded(ROT.GetObject(enumIndex, unkInt)) then
        begin
          if Succeeded(unkInt.QueryInterface(IID_IFileIsInUse, result)) then
          begin
            result := unkInt as IFileIsInUse;
            exit;
          end;
        end;
      end;
    end;
  end;
end;

Conclusion

This whole API has some caveats

• This API relies on a server that registers an interface in the ROT honestly. If an application doesn’t do the effort, you will be unable to aquire the name of it.
• If you lock a file on a shared folder and you want to access the very same file on the local file system, you cannot determine the process if you access the shared folder from localhost. The reason is Windows itself. Windows is the provider of the file to the outer world (even if it is a loopback) so Windows Explorer shows “System” as origin. In the ROT you will see the the UNC path instead of the local file system path. Thus the comparison and our function will fail.
• *Security: A ROT is not really global. In fact, there are several ROTs in the system. ROTs are divided by a user and then the mandatory integrity control (MIC) or integrity levels (IL) high, medium and propably low (didn’t check). If you run as a user, your processes get an medium level and as an Administrator you’ll get an high integrity level. A server that runs with an medium integrity level will only be allowed to register itself into the medium ROT. So it must be started at least once as Administrator to be allowed to create some Registry keys for COM (LOCAL_MACHINE\Classes\AppID\guid). In this way it will be available in all ROTs if it wants. Unfortunately, this is not the end. On a multi user system, every object in a moniker has a security descriptor that tells COM who is allowed to access it. If Alice wants to access an object in the ROT that was created by Bob, Bob has to explicitily grant Alice access to it. By default the security, which allow access to SYSTEM, Administrators and the creator, is copied from the global COM security settings and can be changed either in the registry for an AppID, at process startup or for each registered object by the server. JWSCL provides all of them in JwsclComSecurity.pas (only Subversion trunk and >= 0.9.4). In this way a server can change the settings to, say, allow all authenticated users access to the object.

Downloads

You can download the example file from the Subversion directly.

https://jedi-apilib.svn.sourceforge.net/svnroot/jedi-apilib/jwapi/trunk/Examples/FileIsInUse/Client/FileIsInUseClientExample.dpr

Sequel

The next article discusses the the implementation if the interface IFileIsInUse.

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,

WinAPI

uses
  SysUtils,
  //JwaWindows, //Use either JwaWindows or these JEDI headers:
  JwaWinBase,
  JwaWinType,
  JwaWinNT,
  JwaAclApi,
  JwaAccCtrl,
  JwaWinError,
  JwaSddl;

type
  TOwnerResult = (orNone, orName, orSID);

function GetFileOwner(const FileName: string;
  out Domain, Username: String): TOwnerResult;
var
  pSD: PSecurityDescriptor;
  dwOwnerNameSize, dwDomainNameSize: DWORD;
  pOwnerSID: PSID;
  pszOwnerName, pszDomainName: PChar;
  OwnerType: SID_NAME_USE;
  dwError : DWORD;
begin
  result := orNone;

  pSD := nil;
  dwError := GetNamedSecurityInfo(
     PChar(FileName),//__in       LPTSTR pObjectName,
     SE_FILE_OBJECT,//__in       SE_OBJECT_TYPE ObjectType,
     OWNER_SECURITY_INFORMATION,//__in       SECURITY_INFORMATION SecurityInfo,
     @pOwnerSID,//__out_opt  PSID *ppsidOwner,
     nil,//__out_opt  PSID *ppsidGroup,
     nil,//__out_opt  PACL *ppDacl,
     nil,//__out_opt  PACL *ppSacl,
     pSD//__out_opt  PSECURITY_DESCRIPTOR *ppSecurityDescriptor
   );
  if (dwError <> NOERROR) then
  begin
    SetLastError(dwError);
    RaiseLastOSError;
  end;

  //First get necessary memory size for Owner and Domain
  dwOwnerNameSize  := 0;
  dwDomainNameSize := 0;
  if not LookupAccountSID(nil, pOwnerSID, nil,
    dwOwnerNameSize, nil, dwDomainNameSize, OwnerType) then
  begin
    //Check for SIDs that are unknown on this local system
    if (GetLastError() = ERROR_NONE_MAPPED) then
    begin
      Win32Check(ConvertSidToStringSid(pOwnerSID, pszOwnerName));
      Domain := '';
      Username := pszOwnerName;
      LocalFree(HLOCAL(pszOwnerName));
      result := orSID;
      exit;
    end
    else
    //Any other error exits the function
    if (GetLastError() <> ERROR_INSUFFICIENT_BUFFER) then
      RaiseLastOsError;
  end;

  //Allocate memory for owner and domain
  //Take into account the size of a char type (like WideCHAR)
  GetMem(pszOwnerName, dwOwnerNameSize*sizeof(CHAR));
  try
    GetMem(pszDomainName, dwDomainNameSize*sizeof(CHAR));
    try
      //Retrieve name and domain
      Win32Check(LookupAccountSID(nil, pOwnerSID, pszOwnerName,
        dwOwnerNameSize, pszDomainName, dwDomainNameSize, OwnerType));

      result := orName;

      Domain   := pszDomainName;
      Username := pszOwnerName;
    finally
      FreeMem(pszDomainName);
    end;
  finally
    FreeMem(pszOwnerName);
  end;
end;

The function behaves the following:

• If an WinAPI error occurs the exception EOSError is thrown. You can retrieve the error value from its property Errorcode.
• If the user name could be retrieved the result value is orName and both parameter Domain and UserName contain a value. Otherwise the result is orSID and only UserName contains the User Security Identifier (e.g. S-1-5-21-564352346-2735467565-567745764-1001).

JWSCL

Of course, JWSCL wraps these function calls already. Thus the source size decreases rapidly. See another example here.
In JWSCL it is quite different to implement the function. However the behaviour is equal:

function JwsclGetFileOwner(const FileName: string;
  out Domain, Username: String): TOwnerResult;
var
  F : TJwSecureFileObject;
  Owner : TJwSecurityId;
begin
  F := TJwSecureFileObject.Create(FileName);
  try
    Owner := F.Owner; //Owner is cached/freed by TJwSecureFileObject
    try
      Domain := Owner.GetAccountDomainName();
      Username := Owner.GetAccountName();
      Result := orName;
    except
      on E : EJwsclWinCallFailedException do
      begin
        if E.LastError = ERROR_NONE_MAPPED then
        begin
          Domain := '';
          Username := Owner.StringSID;
          Result := orSID;
        end
        else
          raise;
      end;
    end;
  finally
    F.Free;
  end;
end;

In a next version of JWSCL (currently trunk) the exception handling will be a little bit different:

function JwsclGetFileOwner2(const FileName: string;
  out Domain, Username: String): TOwnerResult;
var
  F : TJwSecureFileObject;
  Owner : TJwSecurityId;
begin
  F := TJwSecureFileObject.Create(FileName);
  try
    Owner := F.Owner; //Owner is cached/freed by TJwSecureFileObject
    try
      Domain := Owner.GetAccountDomainName();
      Username := Owner.GetAccountName();
      Result := orName;
    except
      on E : EJwsclSidNotMappedException do //not mapped error is handled differently
      begin
        Domain := '';
        Username := Owner.StringSID;
        Result := orSID;
      end;
    end;
  finally
    F.Free;
  end;
end;

If you use JWSCL (Version >= 0.9.2a) and enable the compiler switch JWSCL_SIDCACHE in file Include\Jwscl.inc, JWSCL will add a SID cache (for all TJwSecurityID instances globally). In this way LookupAccountSid will be called only once for every unknown SID and thus SIDs that were already translated are retrieved from cache instead.

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

Last time we used the SecurityAttribute parameter in CreateFile to change the security descriptor of the newly created file. However this approach did not add inherited access control elements from the parent folder. We are about to change that.

Filesystem and Registry-key inheritance is implemented since Windows 2000 and also can be added to Windows NT 4 by installing an update. It is a really convenient way to set security over many files in a complex folder tree.

So what did we last time?

This code assigns a simple security descriptor. In my tests there was no way to let CreateFile add the inherited elements to the DACL. Luckily there are several ways to do so.

1. Get the inherited access elements from the parent and add them to our DACL by hand
2. Let the system handle inheritance
3. Do the second way much faster

1. Get the inherited access elements from the parent and add them to our DACL by hand

The first choice needs a lot of work to do. First we need all the inheritable access control elements from the parent folders. This would become very nasty if we had to recursively go up to all parent folders to get the elements. However we are lucky because all inherited ACEs are always available through the direct parent container (if they are not blocked).
Because I will need more time to describe this approach. I’m going to skip this part for now and discuss it in a separate blog entry.

2. Let the system handle inheritance

JWSCL supports inheritance of file, folder and registry keys with the classes TJwSecureFileObject and TJwSecureRegistryKey. We are going to use only TJwSecureFileObject for our task. However changing permissons and inheritance of a registry key is straight forward and is much the same job as it is with files and folders.

TJwSecureFileObject offers three ways to adapt security of a file or folder. You can use a file/folder handle (retrieved by CreateFile), a file or folder name or you use the VCL class TFileStream. However the last variant has some disadvantages like not being able to work with folders.

TJwSecureFileObject retrieves the DACL of the file after newly created file was opened. The method SetDACL sets the DACL back but also removes the protection flag from security descriptor control. Thus all the inherited access elements flow to the file’s access control list.

3. Do the second way which is much less to write

TJwSecureFileObject offers class methods to act with file or folders much faster. We can either restore the inheritance flow by using the file/folder name…

or reestablish the inheritance flow by using a file handle.

You can use one way or the other.

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

Cite:
Inherited permissions on an object are established when it is created. Once the object has been created, you can change the permissions of the parent and it won’t have any effect unless you explicitly ask for the inheritable properties to be re-propagated to the child objects.

Read more about it at Raymond’s blog.

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.

Update

Fixed all the links to the JWSCL Documentation. I didn’t recognize that Doc-O-Matic changed the output tree format of the HTML Help.