NCryptStreamUpdate function (ncryptprotect.h)

The NCryptStreamUpdate function encrypts and decrypts blocks of data.


  [in] const BYTE           *pbData,
       SIZE_T               cbData,
       BOOL                 fFinal


[in] hStream

Handle to the stream object created by calling NCryptStreamOpenToProtect or NCryptStreamOpenToUnprotect.

[in] pbData

Pointer to the byte array to be processed.


Number of bytes in the binary array specified by the pbData parameter.


A Boolean value that specifies whether the last block of data has been processed.

Return value

Returns a status code that indicates the success or failure of the function. Possible return codes include, but are not limited to, the following.

Return code Description
The function was successful.
The content could not be decoded.
The stream handle pointed to by the hStream parameter is not valid.
There was insufficient memory available to process the content.


You must call NCryptStreamOpenToProtect or NCryptStreamOpenToUnprotect to open a stream before calling NCryptStreamUpdate

Messages can be so large that processing them all at once by storing the entire message in memory can be difficult. It is possible, however, to process large messages by partitioning the data to be processed into manageable blocks.

To do this, use NCryptStreamUpdate in a loop that advances through the file block by block. As the streamed message is processed, the resulting output data is passed back to your application by using a callback function that you specify. This is shown by the following example. For more information about the callback function, see PFNCryptStreamOutputCallback.

Note  We recommend against using too small of a block size. Small blocks require more calls and therefore more calling overhead. Further, the streaming APIs are optimized for larger blocks. You should experiment to find the best block size for the data you must process.
BOOL                        fFinal = FALSE;
PBYTE                       pbBuf = NULL;

// Determine the number of bytes to read.
DWORD cbData = GetFileSize( hFileIn, NULL );

// Call NCryptStreamUpdate while there is data left to read.
while(FALSE == fFinal)
    // Read dwBlockSize bytes from the file.
    if(dwBlockSize > 1)
        if( !ReadFile(hFileIn, pbBuf, dwBlockSize, &cbResult, NULL) )
            hr = HRESULT_FROM_WIN32(hr);            
            goto CleanUp;

    // Decrement the number of bytes to read by the current amount read.
    cbData -= cbResult;

    // Set fFinal if there are no bytes left to read.
    if (cbData <= 0) fFinal = TRUE;

    // Encrypt (or decrypt) the bytes pointed to by pbBuf
    hr = NCryptStreamUpdate(hStream, pbBuf, cbResult, fFinal); 
    if( FAILED(hr) )
        goto CleanUp;

    if( NULL != hStream )
    if( NULL != hDescriptor )
        NCryptCloseProtectionDescriptor( hDescriptor );
    if(NULL != pbBuf)
        pbBuf = NULL;


Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header ncryptprotect.h
Library NCrypt.lib
DLL NCrypt.dll

See also

CNG DPAPI Functions