EncryptCallback function

Processes a block of data generated by the Encrypt call to encrypt and store a sequential output stream.

Syntax

FE_ENCRYPT_CALLBACK_ROUTINE EncryptCallback;

bool

EncryptCallback(

    _In_ void *CallbackContext,

    _In_ uint64_t FinalSize,

    _In_ void *StreamData,

    _In_ uint32_t StreamDataLength,

    _In_ bool WriteEncrypted  

)

Parameters

CallbackContext [in]

A buffer containing context data provided to the Encrypt function.

FinalSize [in]

The final size of the encrypted data stream. The resultant output must be exactly this size to be successfully recognized by FESF. See Remarks for more details.

StreamData [in]

A buffer containing the unencrypted data to be written. If WriteEncrypted is TRUE, the application receiving the callback is responsible for encrypting the contents of the data buffer.

StreamDataLength [in]

The length of the data to be written. If WriteEncrypted is TRUE, this will be a multiple of the CipherBlockSize argument passed to Encrypt.

WriteEncrypted [in]

If TRUE, the contents of the Data buffer must be encrypted before storing the output. If FALSE, Data must be written without modification.

Return value

Returns TRUE if the function successfully processes all the data, FALSE otherwise.

For Windows platforms, a specific status code for this function can be reported with SetLastError().

For Linux platforms, the errno variable should be set to report a specific error code.

Remarks

This callback routine is called to provide data to an application to allow the application to produce a data stream that can be interpreted as a valid FESF encrypted file.

If WriteEncrypted is TRUE, the application receiving the callback is responsible for encrypting the supplied Data using key material that can be derived from the SolutionHeader it previously passed to the Encrypt function.  If WriteEncrypted is TRUE and the data supplied in StreamData is not an integer multiple of the CipherBlockSize the application receiving the callback is responsible for padding the data appropriately before performing the encryption operation.

If WriteEncrypted is FALSE, the data supplied in the Data buffer is FESF metadata that must be stored exactly as supplied from the callback, without any change.  These data blocks may not be padded or rounded in size.

Each block of callback data provided to this routine must appear contiguously and the same order in the output stream as it is provided to the callback.

If the encryption algorithm requires an Initialization Vector (IV), the application is required to use the same algorithm that FESF uses to generate a unique IV per cipher block.  For chained ciphers such as CBC, the encryption algorithm is likewise required to implement the same blocking scheme used by FESF.  See About the FESFSa Functions for the description of these issues.

The FinalSize argument defines the ultimate size of the stream, which may be slightly larger than the number of data bytes written to the stream. This argument will be the same each time Callback is called for a given call to Encrypt.

Failure to write the data in the correct order, or failure to make sure that the file is exactly FinalSize bytes long will result in an inconsistent or invalid FESF encrypted file.

Examples

See Also

Requirements