ホーム › Security.Cryptography › NCryptTranslateHandle

NCryptTranslateHandle

関数

レガシーCryptoAPIハンドルをCNGハンドルに変換する。

DLLncrypt.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

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

HRESULT NCryptTranslateHandle(
    NCRYPT_PROV_HANDLE* phProvider,   // optional
    NCRYPT_KEY_HANDLE* phKey,
    UINT_PTR hLegacyProv,
    UINT_PTR hLegacyKey,   // optional
    CERT_KEY_SPEC dwLegacyKeySpec,   // optional
    DWORD dwFlags
);

パラメーター

名前

型

方向

説明

phProvider

NCRYPT_PROV_HANDLE*

outoptional

phKey パラメーターに格納される CNG キーを所有する CNG キーストレージプロバイダーのハンドルを受け取る NCRYPT_PROV_HANDLE 変数へのポインター。このハンドルが不要な場合、このパラメーターは NULL にできます。

phKey

NCRYPT_KEY_HANDLE*

out

CNG キーハンドルを受け取る NCRYPT_KEY_HANDLE 変数へのポインター。

hLegacyProv

UINT_PTR

変換するキーを含む CryptoAPI プロバイダーのハンドル。この関数は、このプロバイダー内のコンテナーにある CryptoAPI キーを変換します。

hLegacyKey

UINT_PTR

inoptional

返されるキーのキー仕様を判別するために使用する CryptoAPI キーのハンドル。このパラメーターは、dwLegacyKeySpec パラメーターに 0 以外の値が含まれている場合は無視されます。

hLegacyKey が NULL で dwLegacyKeySpec が 0 の場合、この関数は hLegacyProv ハンドルからキー仕様を判別しようとします。

dwLegacyKeySpec

CERT_KEY_SPEC

inoptional

キーのキー仕様を指定します。次のいずれかの値を指定できます。

値	意味
0	キーは以下のいずれの種類でもありません。
AT_KEYEXCHANGE 1	キーはキー交換キーです。
AT_SIGNATURE 2	キーは署名キーです。

hLegacyKey が NULL で dwLegacyKeySpec が 0 の場合、この関数は hLegacyProv ハンドルからキー仕様を判別しようとします。

dwFlags

DWORD

この関数の動作を変更するフラグのセット。この関数に対して定義されているフラグはありません。

戻り値の型: HRESULT

公式ドキュメント

CryptoAPI ハンドルを CNG キーハンドルに変換します。

戻り値

関数の成功または失敗を示すステータスコードを返します。

返される可能性のあるコードには、以下が含まれますが、これらに限定されません。

戻り値	説明
ERROR_SUCCESS	関数は成功しました。
NTE_BAD_FLAGS	dwFlags パラメーターに有効でない値が含まれています。
NTE_INVALID_PARAMETER	1 つ以上のパラメーターが有効ではありません。
NTE_NO_MEMORY	メモリ割り当てエラーが発生しました。

解説(Remarks)

これは、現在 CryptoAPI を使用しているアプリケーションやシステムコンポーネントが CNG の使用へ円滑に移行できるよう支援することを目的としたヘルパー関数です。

この関数は、hLegacyProv パラメーターで参照される暗号化サービスプロバイダー (CSP) の名前と同一の名前またはエイリアスを持つ CNG キーストレージプロバイダーが登録されている場合にのみ成功します。

この関数は、CSP ハンドルを CNG キーハンドルに変換するために、次の手順を実行します。

hLegacyProv ハンドルから CSP の名前を取得します。
CSP 名と同一の名前またはエイリアスを持つ CNG プロバイダーを開きます。
CSP 内の現在のキーコンテナーの名前を取得します。
CryptoAPI キーを取得し、それを CNG キーに変換して、phKey パラメーターで返します。

サービスは、StartService 関数からこの関数を呼び出してはなりません。サービスが StartService 関数からこの関数を呼び出すと、デッドロックが発生し、サービスが応答しなくなる可能性があります。

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

各言語での呼び出し定義

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

HRESULT NCryptTranslateHandle(
    NCRYPT_PROV_HANDLE* phProvider,   // optional
    NCRYPT_KEY_HANDLE* phKey,
    UINT_PTR hLegacyProv,
    UINT_PTR hLegacyKey,   // optional
    CERT_KEY_SPEC dwLegacyKeySpec,   // optional
    DWORD dwFlags
);

[DllImport("ncrypt.dll", ExactSpelling = true)]
static extern int NCryptTranslateHandle(
    IntPtr phProvider,   // NCRYPT_PROV_HANDLE* optional, out
    out UIntPtr phKey,   // NCRYPT_KEY_HANDLE* out
    UIntPtr hLegacyProv,   // UINT_PTR
    UIntPtr hLegacyKey,   // UINT_PTR optional
    uint dwLegacyKeySpec,   // CERT_KEY_SPEC optional
    uint dwFlags   // DWORD
);

<DllImport("ncrypt.dll", ExactSpelling:=True)>
Public Shared Function NCryptTranslateHandle(
    phProvider As IntPtr,   ' NCRYPT_PROV_HANDLE* optional, out
    <Out> ByRef phKey As UIntPtr,   ' NCRYPT_KEY_HANDLE* out
    hLegacyProv As UIntPtr,   ' UINT_PTR
    hLegacyKey As UIntPtr,   ' UINT_PTR optional
    dwLegacyKeySpec As UInteger,   ' CERT_KEY_SPEC optional
    dwFlags As UInteger   ' DWORD
) As Integer
End Function

' phProvider : NCRYPT_PROV_HANDLE* optional, out
' phKey : NCRYPT_KEY_HANDLE* out
' hLegacyProv : UINT_PTR
' hLegacyKey : UINT_PTR optional
' dwLegacyKeySpec : CERT_KEY_SPEC optional
' dwFlags : DWORD
Declare PtrSafe Function NCryptTranslateHandle Lib "ncrypt" ( _
    ByVal phProvider As LongPtr, _
    ByRef phKey As LongPtr, _
    ByVal hLegacyProv As LongPtr, _
    ByVal hLegacyKey As LongPtr, _
    ByVal dwLegacyKeySpec As Long, _
    ByVal dwFlags As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

NCryptTranslateHandle = ctypes.windll.ncrypt.NCryptTranslateHandle
NCryptTranslateHandle.restype = ctypes.c_int
NCryptTranslateHandle.argtypes = [
    ctypes.c_void_p,  # phProvider : NCRYPT_PROV_HANDLE* optional, out
    ctypes.c_void_p,  # phKey : NCRYPT_KEY_HANDLE* out
    ctypes.c_size_t,  # hLegacyProv : UINT_PTR
    ctypes.c_size_t,  # hLegacyKey : UINT_PTR optional
    wintypes.DWORD,  # dwLegacyKeySpec : CERT_KEY_SPEC optional
    wintypes.DWORD,  # dwFlags : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ncrypt.dll')
NCryptTranslateHandle = Fiddle::Function.new(
  lib['NCryptTranslateHandle'],
  [
    Fiddle::TYPE_VOIDP,  # phProvider : NCRYPT_PROV_HANDLE* optional, out
    Fiddle::TYPE_VOIDP,  # phKey : NCRYPT_KEY_HANDLE* out
    Fiddle::TYPE_UINTPTR_T,  # hLegacyProv : UINT_PTR
    Fiddle::TYPE_UINTPTR_T,  # hLegacyKey : UINT_PTR optional
    -Fiddle::TYPE_INT,  # dwLegacyKeySpec : CERT_KEY_SPEC optional
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "ncrypt")]
extern "system" {
    fn NCryptTranslateHandle(
        phProvider: *mut usize,  // NCRYPT_PROV_HANDLE* optional, out
        phKey: *mut usize,  // NCRYPT_KEY_HANDLE* out
        hLegacyProv: usize,  // UINT_PTR
        hLegacyKey: usize,  // UINT_PTR optional
        dwLegacyKeySpec: u32,  // CERT_KEY_SPEC optional
        dwFlags: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ncrypt.dll")]
public static extern int NCryptTranslateHandle(IntPtr phProvider, out UIntPtr phKey, UIntPtr hLegacyProv, UIntPtr hLegacyKey, uint dwLegacyKeySpec, uint dwFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ncrypt_NCryptTranslateHandle' -Namespace Win32 -PassThru
# $api::NCryptTranslateHandle(phProvider, phKey, hLegacyProv, hLegacyKey, dwLegacyKeySpec, dwFlags)

#uselib "ncrypt.dll"
#func global NCryptTranslateHandle "NCryptTranslateHandle" sptr, sptr, sptr, sptr, sptr, sptr
; NCryptTranslateHandle varptr(phProvider), varptr(phKey), hLegacyProv, hLegacyKey, dwLegacyKeySpec, dwFlags   ; 戻り値は stat
; phProvider : NCRYPT_PROV_HANDLE* optional, out -> "sptr"
; phKey : NCRYPT_KEY_HANDLE* out -> "sptr"
; hLegacyProv : UINT_PTR -> "sptr"
; hLegacyKey : UINT_PTR optional -> "sptr"
; dwLegacyKeySpec : CERT_KEY_SPEC optional -> "sptr"
; dwFlags : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ncrypt.dll"
#cfunc global NCryptTranslateHandle "NCryptTranslateHandle" var, var, sptr, sptr, int, int
; res = NCryptTranslateHandle(phProvider, phKey, hLegacyProv, hLegacyKey, dwLegacyKeySpec, dwFlags)
; phProvider : NCRYPT_PROV_HANDLE* optional, out -> "var"
; phKey : NCRYPT_KEY_HANDLE* out -> "var"
; hLegacyProv : UINT_PTR -> "sptr"
; hLegacyKey : UINT_PTR optional -> "sptr"
; dwLegacyKeySpec : CERT_KEY_SPEC optional -> "int"
; dwFlags : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ncrypt.dll"
#cfunc global NCryptTranslateHandle "NCryptTranslateHandle" sptr, sptr, sptr, sptr, int, int
; res = NCryptTranslateHandle(varptr(phProvider), varptr(phKey), hLegacyProv, hLegacyKey, dwLegacyKeySpec, dwFlags)
; phProvider : NCRYPT_PROV_HANDLE* optional, out -> "sptr"
; phKey : NCRYPT_KEY_HANDLE* out -> "sptr"
; hLegacyProv : UINT_PTR -> "sptr"
; hLegacyKey : UINT_PTR optional -> "sptr"
; dwLegacyKeySpec : CERT_KEY_SPEC optional -> "int"
; dwFlags : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。