A Policy DLL's PolGetKeyFromHeader callback function returns the key and encryption algorithm for an existing encrypted file, given the accessing thread ID, the file path and policy header data.
POL_GET_KEY_FROM_HEADER PolGetKeyFromHeader;
bool
PolGetKeyFromHeader(
_In_ FE_POLICY_PATH_INFORMATION *PolicyPathInfo,
_In_ DWORD ThreadId,
_In_ PVOID PolHeaderData,
_In_ DWORD PolHeaderDataSize,
_Out_ LPCWSTR *PolUniqueAlgorithmId,
_Out_ PVOID *PolKey,
_Out_ DWORD *PolKeySize,
_Outptr_result_maybenull_ PVOID *CleanupInfo,
)
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.
PolHeaderData [in]
A pointer to an FESF allocated storage area containing the Policy DLL Header Data that FESF retrieved from the file. This data was previously provided to FESF by the Policy DLL as output from a successful call to PolGetKeyNewFile.
PolHeaderDataSize [in]
The size, in bytes, of the header data provided in the buffer pointed to by PolHeaderData.
PolUniqueAlgorithmId [out]
A pointer to a wide character string representing the encryption algorithm and properties to be used to encrypt and decrypt file data. PolUniqueAlgorithmId must match one previously specified by the Policy DLL in the FE_POLICY_CONFIG structure passed to FePolicySetConfiguration.
PolKey [out]
A pointer to a storage area allocated by the Policy DLL containing encryption key data. FESF will pass this key data to the CNG cryptographic algorithm provider indicated by Algorithm. FESF calls the Policy DLL's PolFreeKey callback function when it no longer needs the key data and the allocated storage can be freed.
PolKeySize [out]
The size, in bytes, of the key data in the buffer pointed to by PolKey.
CleanupInfo [out, opt]
A pointer to a Policy DLL defined context value that
will be passed to the Policy DLL's PolReportLastHandleClosed callback
function. This parameter is optional and may be NULL.
If this value is specified and
the file already has a CleanupInfo registered then you will be called back at
PolReportLastHandleClosed with the previous
value to CleanupInfo.
To indicate success, and that it is supplying valid values for all output parameters, the PolGetKeyFromHeader callback function returns TRUE. Otherwise, it returns FALSE.
If FALSE is returned, the thread's CreateFile operation will fail with an error. See the Remarks section for more information on the consequences of returning FALSE.
All Policy DLLs must implement this callback function.
A Policy DLL's PolGetKeyFromHeader callback function is called by FESF to determine the encryption algorithm and key data to be used by the CNG provider to encrypt or decrypt data in an existing FESF encrypted file. This function is always called after a call to PolGetPolicyExistingFile has returned FE_POLICY_ENCRYPT_DECRYPT and FESF does not already have key information for the file.
As previously described, encryption key data is interpreted by FESF as an opaque data block that it passes to the CNG provider, for use as an encryption key. FESF does not interpret or verify this key data. For custom CNGs this transparent key data could be an indirect reference to something maintained by the custom CNG that provides the actual symmetric key used to encrypt and decrypt the file's data.
The Policy DLL derives the encryption algorithm and key data from the provided thread, header and FE_POLICY_PATH_INFORMATION for the file.
The CleanupInfo parameter is reserved for future use.
PolGetKeyFromHeader 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 PolGetKeyFromHeader occurs after CreateFile has succeeded but before the final result is returned to the thread. Because the PolGetKeyFromHeader callback is blocking CreateFile from completing, processing in this function must be prompt.
Policy DLLs should return FALSE from their PolGetKeyFromHeader callback only when absolutely necessary. Because PolGetKeyFromHeader is called after Windows CreateFile processing has completed, returning FALSE will result in a new zero length file being created or, perhaps, a previously existing file being overwritten with a new zero length file. For more information, see Returning Failure from Policy DLL Callbacks.
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.
|
Software version |
FESF V1 (and later) |
|
Library |
FESFPolicy.lib |
|
Header |
PolDllApi.h |