Swapping buffers in minifilter)

The following is taken from the filter driver developer guide:

Certain minifilters need to swap the suppliedbuffer for certain operations. consider a minifilter that implements customencryption. on a non-cached irp_mj_read, it normally wishes to decrypt thecontents of the buffer that was read from the filesystem. similarly
On a write, it wishes to encrypt the contents. Take the latter case: the contents cannot beencrypted in place, because for example, the maximal access to the bufferthat the minifilter can assume is ioreadaccess.

Hence the minifilter needs to supplant its ownbuffer which has read/write access, encrypt the contents of the original bufferinto the new one, and send the I/O down.

For this scenario, the filter manager supportsbuffer-switching. However there are a few rules to which the minifilter mustadhere:

1. minifilters that switch a buffer must supply a post-callback. Thisis so that the buffer can be switched back by filter manager automatically.

2. if the minifilter is switching the buffer for an operation for whichfltfl_callback_data_system_buffer flag was set, it must ensure that the new buffer is from non-pagedmemory (I. e. either from non-paged pool or from locked down memory ).

3. if the above flag was not set, minifilter must adhere to therequirements of the device (by looking at the deviceobjectflags etc. in thevolume properties) When supplanting the buffer, based on the operation. forinstance if it supports direct I/O, it
Must supply a MDL etc.

4. if the minifilter supplants a non-paged pool buffer for an operationfor which the specified flag is not set, it must also build a MDL via mmbuildmdlfornonpagedpool () and supply it in the mdladdress field. this is so that afilter/filesystem
Below will not attempt to lock non-paged pool (which canassert on checked windows builds, and is also not good from a very ceperspective ). if a MDL is supplied, filters/file systems will always access the buffer through the MDL (byobtaining a system address
For it ).

5. when switching a buffer, the minifilter shoshould also switch the MDL (I. e. the buffer and the MDL Must Be In Sync ). it is fine to leave the MDL nullsubject to the usual direct I/O exceptions.

6. minifilter shocould not free the old buffer/old MDL.

7. minifilter shocould not attempt to switch back the old buffer/MDL inits post-callback. filter manager does this automatically. in fact thebuffer/MDL the minifilter sees in the iopb in its post-callback are theoriginal ones. minifilters can remember
The switched buffer by passing it invia their completion context.

8. minifilters are expected to free the buffer they allocated (andsupplanted) in the Post-callback. Filter manager however, Will automaticallyfree the mdl for the swapped buffer if any.

9. minifilters that do not want filter manager to automatically Freethe mdl for the swapped buffer can call fltretainswappedbuffermdl ().

10. minifilters that wish to access the swapped buffer's MDL can use fltgetswappedbuffermdl () in the Post-callback. since a filter/filesystem below theminifilter that swapped the new buffer in, may potentially create a MDL for it, filter manager saves
Any such mdl for the swapped buffer before calling thepost-callback for the minifilter that swapped the buffers. This API can be usedto access the MDL in that case.

Chu's mad man, Chu Daxia, translated this part of the content in the Windows File System filtering driver development tutorial (version 2), as follows:

Some micro-filters must exchange buffering for some operations. Consider a micro-filter to implement an encryption algorithm. For a non-buffered (non-cached) irp_mj_read, it generally wants to decrypt the data in the buffer. Similarly, when writing, it wants to encrypt the content. Consider the following: The content cannot be encrypted in this space. For irp_mj_write, this microfilter may only have ioreadaccess permissions.
 
Therefore, a micro-filter must replace the original buffer with its own buffer with read/write permissions. After the content in the original buffer zone is encrypted and written to the new buffer zone, the I/O request is passed.

Therefore, the filter Manager supports buffer conversion. The following rules must be observed:
1. The microfilter that changes the buffer zone must have a corresponding post-operation callback. In this way, the buffer can be automatically converted back by the filter manager.
2. if the change is a buffer marked with fltfl_callback_data_system_buffer, ensure that the new buffer is non-Paging memory. (For example, from non-Paging memory pool or locked memory ).
3. If the above tag is not set, the micro-filter must determine the buffer type according to the requirements of the device object (you can view the tags such as deviceobjectflags in the volume attribute ). For example, if direct I/O is supported, MDL must be provided.
4. If the micro-filter uses the buffer in the non-Paging pool to perform an operation without fltfl_callback_data_system_buffer, it must also use mubuildmdlfornonpagedpool () and fill the address in the mdladdress domain. This is because any of the following filters or file systems do not need to attempt to lock non-Paging pools (assertions can be used during construction, but they are not efficient ), if an MDL is provided, the filter and file system can always access it through the MDL access buffer (a system memory address can be obtained to access it ).
5. When replacing a buffer, the microfilter must also replace the MDL (that is, the buffer and MDL must be synchronized ). For general direct I/O exceptions, you can leave MDL empty.
6. The micro-filter should not release the old MDL and buffer space.
7. Do not try to replace the old buffer and the MDL. Filter manager automatically execute these operations in the subsequent operation callback. In fact, the buffer space and MDL are old in the iopb of the microfilter in the post-operation callback (Note: Before replacement ). The microfilter must record a new buffer in the context.
8. The microfilter should release its own allocated (and replaced) buffer. In any case, the filter Manager Automatically releases the MDL of the new buffer.
9. The microfilter does not want the filter manager to automatically release the exchanged buffer MDL. You can call fltretainswappedbuffermdl ().
10. If the filter wants to access the cached MDL that has been exchanged, you can use fltgetswappedbuffermdl () in the subsequent operation callback (). Since a lower-level filter or file system exchanges a new buffer space, an MDL may be generated. The filter manager saves all such MDL before the microfilter exchange buffer in the subsequent operation callback. This call can be used to access these MDL.