ホーム › Security.Cryptography › NCryptStreamUpdate

NCryptStreamUpdate

関数

保護/復号ストリームにデータを順次入力して処理する。

DLLncrypt.dll呼出規約winapi対応OSwindows8.0

シグネチャ

// ncrypt.dll
#include <windows.h>

HRESULT NCryptStreamUpdate(
    NCRYPT_STREAM_HANDLE hStream,
    const BYTE* pbData,
    UINT_PTR cbData,
    BOOL fFinal
);

パラメーター

名前	型	方向	説明
hStream	NCRYPT_STREAM_HANDLE	in	NCryptStreamOpenToProtect または NCryptStreamOpenToUnprotect を呼び出して作成したストリームオブジェクトへのハンドルです。
pbData	BYTE*	in	処理対象のバイト配列へのポインターです。
cbData	UINT_PTR	in	pbData パラメーターで指定されたバイナリ配列のバイト数です。
fFinal	BOOL	in	データの最後のブロックが処理されたかどうかを指定するブール値です。

戻り値の型: HRESULT

公式ドキュメント

データのブロックを暗号化および復号します。

戻り値

関数の成功または失敗を示すステータスコードを返します。返される可能性のあるコードには、以下が含まれますが、これらに限定されません。

戻り値コード	説明
ERROR_SUCCESS	関数は成功しました。
NTE_BAD_DATA	コンテンツをデコードできませんでした。
NTE_INVALID_HANDLE	hStream パラメーターが指すストリームハンドルが無効です。
NTE_NO_MEMORY	コンテンツを処理するための十分なメモリがありませんでした。

解説(Remarks)

NCryptStreamUpdate を呼び出す前に、NCryptStreamOpenToProtect または NCryptStreamOpenToUnprotect を呼び出してストリームを開く必要があります。

メッセージが非常に大きい場合、メッセージ全体をメモリに格納して一度にすべてを処理することは困難になることがあります。しかし、処理対象のデータを扱いやすいブロックに分割することで、大きなメッセージを処理することが可能です。

これを行うには、ファイルをブロック単位で順に進めるループ内で NCryptStreamUpdate を使用します。ストリーミングされたメッセージが処理されると、結果として得られる出力データは、指定したコールバック関数を介してアプリケーションに渡されます。これは次の例で示されています。コールバック関数の詳細については、PFNCryptStreamOutputCallback を参照してください。

注意ブロックサイズを小さくしすぎないことを推奨します。ブロックが小さいと呼び出し回数が増え、その分だけ呼び出しのオーバーヘッドが大きくなります。さらに、ストリーミング API はより大きなブロックに最適化されています。処理対象のデータに最適なブロックサイズを見つけるために、試行することをお勧めします。

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ncrypt.dll
#include <windows.h>

HRESULT NCryptStreamUpdate(
    NCRYPT_STREAM_HANDLE hStream,
    const BYTE* pbData,
    UINT_PTR cbData,
    BOOL fFinal
);

[DllImport("ncrypt.dll", ExactSpelling = true)]
static extern int NCryptStreamUpdate(
    IntPtr hStream,   // NCRYPT_STREAM_HANDLE
    IntPtr pbData,   // BYTE*
    UIntPtr cbData,   // UINT_PTR
    bool fFinal   // BOOL
);

<DllImport("ncrypt.dll", ExactSpelling:=True)>
Public Shared Function NCryptStreamUpdate(
    hStream As IntPtr,   ' NCRYPT_STREAM_HANDLE
    pbData As IntPtr,   ' BYTE*
    cbData As UIntPtr,   ' UINT_PTR
    fFinal As Boolean   ' BOOL
) As Integer
End Function

' hStream : NCRYPT_STREAM_HANDLE
' pbData : BYTE*
' cbData : UINT_PTR
' fFinal : BOOL
Declare PtrSafe Function NCryptStreamUpdate Lib "ncrypt" ( _
    ByVal hStream As LongPtr, _
    ByVal pbData As LongPtr, _
    ByVal cbData As LongPtr, _
    ByVal fFinal As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

NCryptStreamUpdate = ctypes.windll.ncrypt.NCryptStreamUpdate
NCryptStreamUpdate.restype = ctypes.c_int
NCryptStreamUpdate.argtypes = [
    wintypes.HANDLE,  # hStream : NCRYPT_STREAM_HANDLE
    ctypes.POINTER(ctypes.c_ubyte),  # pbData : BYTE*
    ctypes.c_size_t,  # cbData : UINT_PTR
    wintypes.BOOL,  # fFinal : BOOL
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ncrypt.dll')
NCryptStreamUpdate = Fiddle::Function.new(
  lib['NCryptStreamUpdate'],
  [
    Fiddle::TYPE_VOIDP,  # hStream : NCRYPT_STREAM_HANDLE
    Fiddle::TYPE_VOIDP,  # pbData : BYTE*
    Fiddle::TYPE_UINTPTR_T,  # cbData : UINT_PTR
    Fiddle::TYPE_INT,  # fFinal : BOOL
  ],
  Fiddle::TYPE_INT)

#[link(name = "ncrypt")]
extern "system" {
    fn NCryptStreamUpdate(
        hStream: *mut core::ffi::c_void,  // NCRYPT_STREAM_HANDLE
        pbData: *const u8,  // BYTE*
        cbData: usize,  // UINT_PTR
        fFinal: i32  // BOOL
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ncrypt.dll")]
public static extern int NCryptStreamUpdate(IntPtr hStream, IntPtr pbData, UIntPtr cbData, bool fFinal);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ncrypt_NCryptStreamUpdate' -Namespace Win32 -PassThru
# $api::NCryptStreamUpdate(hStream, pbData, cbData, fFinal)

#uselib "ncrypt.dll"
#func global NCryptStreamUpdate "NCryptStreamUpdate" sptr, sptr, sptr, sptr
; NCryptStreamUpdate hStream, varptr(pbData), cbData, fFinal   ; 戻り値は stat
; hStream : NCRYPT_STREAM_HANDLE -> "sptr"
; pbData : BYTE* -> "sptr"
; cbData : UINT_PTR -> "sptr"
; fFinal : BOOL -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ncrypt.dll"
#cfunc global NCryptStreamUpdate "NCryptStreamUpdate" sptr, var, sptr, int
; res = NCryptStreamUpdate(hStream, pbData, cbData, fFinal)
; hStream : NCRYPT_STREAM_HANDLE -> "sptr"
; pbData : BYTE* -> "var"
; cbData : UINT_PTR -> "sptr"
; fFinal : BOOL -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ncrypt.dll"
#cfunc global NCryptStreamUpdate "NCryptStreamUpdate" sptr, sptr, sptr, int
; res = NCryptStreamUpdate(hStream, varptr(pbData), cbData, fFinal)
; hStream : NCRYPT_STREAM_HANDLE -> "sptr"
; pbData : BYTE* -> "sptr"
; cbData : UINT_PTR -> "sptr"
; fFinal : BOOL -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。