PolGetKeyNewFile callback function   

A Policy DLL's PolGetKeyNewFile callback function provides key material for a new file that is to be stored in encrypted format.

Syntax

POL_GET_KEY_NEW_FILE PolGetKeyNewFile;

bool

PolGetKeyNewFile(

    _In_  FE_POLICY_PATH_INFORMATION *PolicyPathInfo,

    _In_  DWORD ThreadId,

    _In_  PVOID Context,

    _Out_ PVOID *PolHeaderData,

    _Out_ DWORD *PolHeaderDataSize,

    _Out_ LPCWSTR *PolUniqueAlgorithmId,

    _Out_ PVOID *PolKey,

    _Out_ DWORD *PolKeySize,

    _Outptr_result_maybenull_ PVOID *CleanupInfo,

)

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.

Context[in]

Caller-supplied value previously returned as output from the PolGetPolicyNewFile callback.

PolHeaderData [out]

A pointer to a storage area allocated by the Policy DLL containing Policy DLL defined Header Data for FESF to store with the newly created file.  FESF calls the Policy DLL's PolFreeHeader callback function when it no longer needs the header data.

PolHeaderDataSize [out]

The size, in bytes, of the header data returned 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 an 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 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

Return value

To indicate success, and that it is supplying valid values for all output parameters, the PolGetPolicyNewFile 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.

Remarks

All Policy DLLs must implement this callback function.

A Policy DLL's PolGetKeyNewFile callback function is called by FESF to determine the encryption algorithm and key data for a new file that will be stored in encrypted format. This function is always called after a call to PolGetPolicyNewFile has returned FE_POLICY_ENCRYPT_DECRYPT.

Prior to the first write to a file stored in FESF encrypted format, FESF stores the Policy DLL Header Data returned in PolHeaderData from this function as well as certain FESF control information in the file.  FESF stores the Header Data exactly as it is provided by the Policy DLL.  FESF does not encrypt this data.

Once a file's data has been encrypted by FESF, when the file is opened for encrypt/decrypt access and FESF does not already have key information for the file, the Header Data will be retrieved from the file and returned to the Policy DLL at its PolGetKeyFromHeader callback function.  Given this Header Data the Policy DLL must be able to derive the same encryption Algorithm ID, Key Data, and Key Size that are returned here in the PolUniqueAlgorithmId, PolKey, and PolKeySize parameters.  See the description of the PolGetKeyFromHeader callback function for more information.

Note that encryption key data is interpreted by FESF as a transparent block of data that it passes to the CNG provider, for use as an encryption key.  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.

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

Policy DLLs should return FALSE from their PolGetKeyNewFile callback only when absolutely necessary.  Because PolGetKeyNewFile is called after Windows system service 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.

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