NCryptStreamUpdate-Funktion (ncryptprotect.h)

Artikel
02/29/2024

Die NCryptStreamUpdate-Funktion verschlüsselt und entschlüsselt Datenblöcke.

Syntax

SECURITY_STATUS NCryptStreamUpdate(
  [in] NCRYPT_STREAM_HANDLE hStream,
  [in] const BYTE           *pbData,
       SIZE_T               cbData,
       BOOL                 fFinal
);

Parameter

[in] hStream

Handle an das Streamobjekt, das durch Aufrufen von NCryptStreamOpenToProtect oder NCryptStreamOpenToUnprotect erstellt wurde.

[in] pbData

Zeiger auf das zu verarbeitende Bytearray.

cbData

Anzahl der Bytes in dem binären Array, das durch den pbData-Parameter angegeben wird.

fFinal

Ein boolescher Wert, der angibt, ob der letzte Datenblock verarbeitet wurde.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt. Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion war erfolgreich.
NTE_BAD_DATA	Der Inhalt konnte nicht decodiert werden.
NTE_INVALID_HANDLE	Das Streamhandle, auf das der hStream-Parameter verweist, ist ungültig.
NTE_NO_MEMORY	Es war nicht genügend Arbeitsspeicher verfügbar, um den Inhalt zu verarbeiten.

Hinweise

Sie müssen NCryptStreamOpenToProtect oder NCryptStreamOpenToUnprotect aufrufen, um einen Stream zu öffnen, bevor Sie NCryptStreamUpdate aufrufen.

Nachrichten können so groß sein, dass es schwierig sein kann, sie alle gleichzeitig zu verarbeiten, indem die gesamte Nachricht im Arbeitsspeicher gespeichert wird. Es ist jedoch möglich, große Nachrichten zu verarbeiten, indem die zu verarbeitenden Daten in verwaltbare Blöcke partitioniert werden.

Verwenden Sie dazu NCryptStreamUpdate in einer Schleife, die die Datei Block für Block durchläuft. Während die gestreamte Nachricht verarbeitet wird, werden die resultierenden Ausgabedaten mithilfe einer von Ihnen angegebenen Rückruffunktion an Ihre Anwendung zurückgegeben. Dies wird im folgenden Beispiel gezeigt. Weitere Informationen zur Rückruffunktion finden Sie unter PFNCryptStreamOutputCallback.

Hinweis Es wird davon abgeraten, eine zu kleine Blockgröße zu verwenden. Kleine Blöcke erfordern mehr Anrufe und damit mehr Anrufmehraufwand. Darüber hinaus sind die Streaming-APIs für größere Blöcke optimiert. Sie sollten experimentieren, um die beste Blockgröße für die Daten zu finden, die Sie verarbeiten müssen.

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;
    }         
}      

CleanUp:
    if( NULL != hStream )
    {
        NCryptStreamClose(hStream);
    }
    if( NULL != hDescriptor )
    {
        NCryptCloseProtectionDescriptor( hDescriptor );
    }
    if(NULL != pbBuf)
    {
        LocalFree(pbBuf);
        pbBuf = NULL;
    }

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ncryptprotect.h
Bibliothek	NCrypt.lib
DLL	NCrypt.dll

Weitere Informationen

CNG DPAPI-Funktionen

NCRYPT_PROTECT_STREAM_INFO

NCryptStreamOpenToProtect

NCryptStreamOpenToUnprotect

Freigeben über