PolGetPolicyNewFile callback function

A Policy DLL's PolGetPolicyNewFile callback function determines whether a new file should be created in encrypted or non-encrypted format.

Syntax

POL_GET_POLICY_NEW_FILE PolGetPolicyNewFile;

FE_POLICY_RESULT

PolGetPolicyNewFile(

    _In_  FE_POLICY_PATH_INFORMATION *PolicyPathInfo,

    _In_  DWORD ThreadId,

    _In_  DWORD GrantedAccess,

    _In_  DWORD CreateAction,

    _Out_ PVOID *Context

)

Parameters

PolicyPathInfo [in]

A pointer to an FESF allocated FE_POLICY_PATH_INFORMATION structure describing the file being created.

ThreadId [in]

The identifier of the thread creating the file.

GrantedAccess [in]

A bitmask representing the File Access Rights that the thread creating the file has been granted.  File Access Rights are represented by standard Windows-defined constants as follows:

CreateAction [in]

A value indicating the action taken as a result of the thread's CreateFile call.  The CreateAction will be one of the following constant values:

See the Remarks section for additional information regarding the meaning of these parameters.

Context [out]

A Policy DLL determined value for FESF to pass to the matching PolGetKeyNewFile callback (which will immediately follow if this function returns FE_POLICY_ENCRYPT_DECRYPT). 

Return value

The PolGetPolicyNewFile callback function returns an enumeration value of the type FE_POLICY_RESULT indicating the encryption policy for a new file that is being created.

To cause the file to be created with encrypted data, PolGetPolicyNewFile returns the enumeration value FE_POLICY_ENCRYPT_DECRYPT.  To cause the file to be created with non-encrypted (raw, cleartext) data, PolGetPolicyNewFile returns the enumeration value FE_POLICY_RAW.

If PolGetPolicyNewFile cannot specify an encryption policy for the newly created file, for example due to an error in processing, PolGetPolicyNewFile returns the enumeration value FE_POLICY_FAIL.  This will cause the thread's CreateFile operation to fail with an error. 

Remarks

All Policy DLLs must implement this callback function.

A Policy DLL's PolGetPolicyNewFile callback function is called by FESF to determine the policy for a new file.  Policy defines whether the data written by the thread indicated by ThreadID will be stored encrypted or unencrypted.  The policy for a given file can be based on the parameters passed into this function as well as any additional information PolGetPolicyNewFile acquires on its own.

Given the ThreadID provided in this callback, a Solution can call FESF-provided helper functions to retrieve information about the calling thread, including the directory and file name of the executing program and the Security Identifier (SID) of the account under which the thread is running.  Given the SID, the Solution can get the associated username (for example, one way to do this in C++ is by calling the Windows functions ConvertStringSidToSid and LookupAccountSid).

Whenever PolGetPolicyNewFile returns FE_POLCY_ENCRYPT_DECRYPT, FESF will call the Policy DLL at its PolGetKeyNewFile callback function to retrieve the Algorithm ID, Key, and Policy DLL Header Data for the file.

It is important to understand that FESF considers all of the following "new files" and will therefore call PolGetPolicyNewFile when opening:

•      A file on a supported file system that previously did not exist.  In this case CreateAction will be POL_CREATE_ACTION_CREATED.

•      A file on a supported file system that is not encrypted by FESF and is zero data bytes in length.  In this case CreateAction will be POL_CREATE_ACTION_OPENED.

•      A file on a supported file system that is either encrypted or not encrypted by FESF and is the subject of a "destructive create."  A destructive create is one with a CreateAction of POL_CREATE_ACTION_SUPERSEDED or POL_CREATE_ACTION_OVERWRITTEN.

The POL_CREATE_ACTION_* values are direct translations of Windows native FILE_* CreateDisposition values.  You can read more about the specific meaning of each of these values in the MSDN documentation for the Windows NtCreateFile function.  This documentation makes clear the difference between, for example, POL_CREATE_ACTION_SUPERSEDED and POL_CREATE_ACTION_OVERWRITTEN.

When FESF Policy Caching is enabled, if the process owning the ThreadID opens this file in the future with the same access described by GrantedAccess, FESF may automatically grant FE_POLCY_ENCRYPT_DECRYPT access to this file.  This can help to reduce system overhead, by avoiding a future call to PolGetPolicyExistingFile. For more information, see FESF Policy Caching.

PolGetPolicyNewFile is called as part of Windows' processing a CreateFile call made by the thread indicated by ThreadID for the file described by PolicyPathInfo.  The call to PolGetPolicyNewFile occurs after CreateFile has succeeded but before the final result is returned to the thread.  Because the PolGetPolicyNewFile callback is blocking CreateFile from completing, processing in this function must be prompt.

Policy DLLs should return FE_POLICY_FAIL from their PolGetPolicyNewFile callback only when absolutely necessary.  Because PolGetPolicyNewFile is called after Windows CreateFile processing has completed, returning FE_POLICY_FAIL will result in a new zero length file being created or, perhaps, a previously existing file being overwritten with a new zero length file.  The specific action taken as a result of CreateFile is indicated by CreateAction.  For more information see Returning Failure from Policy DLL Callbacks.

Examples

See Also

The FESF Sample Solution contains an example implementation of this callback function.  This example is part of the provided UM_Sample Visual Studio Solution, the SampPolicy project, and is located in the file SampPolicy.cpp.

Requirements