ホーム › Security.Cryptography › CryptAcquireContextA

CryptAcquireContextA

関数

暗号化サービスプロバイダーのコンテキストハンドルを取得する(ANSI版)。

DLLADVAPI32.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

BOOL CryptAcquireContextA(
    UINT_PTR* phProv,
    LPCSTR szContainer,   // optional
    LPCSTR szProvider,   // optional
    DWORD dwProvType,
    DWORD dwFlags
);

パラメーター

名前型方向説明

phProv UINT_PTR* out CSP のハンドルへのポインター。CSP の使用を終えたら、CryptReleaseContext 関数を呼び出してハンドルを解放してください。

szContainer

LPCSTR

inoptional

キーコンテナー名。これは、キーコンテナーを CSP に対して識別する null 終端文字列です。この名前は、キーの格納方法とは独立しています。CSP の中には、キーコンテナーを内部的に (ハードウェア内に) 格納するもの、システムレジストリを使用するもの、ファイルシステムを使用するものがあります。ほとんどの場合、dwFlags に CRYPT_VERIFYCONTEXT を設定するときは、szContainer を NULL に設定する必要があります。ただし、スマートカード CSP などのハードウェアベースの CSP では、指定したコンテナー内の公開されている情報にアクセスできます。

szContainer パラメーターの使用方法の詳細については、解説を参照してください。

szProvider

LPCSTR

inoptional

使用する CSP の名前を含む null 終端文字列。

このパラメーターが NULL の場合、ユーザーの既定のプロバイダーが使用されます。詳細については、Cryptographic Service Provider Contexts を参照してください。使用可能な暗号化プロバイダーの一覧については、Cryptographic Provider Names を参照してください。

アプリケーションは、CryptGetProvParam 関数を使用して dwParam パラメーターで PP_NAME CSP 値を読み取ることにより、使用中の CSP の名前を取得できます。

既定の CSP はオペレーティングシステムのリリース間で変わる可能性があります。異なるオペレーティングシステムプラットフォーム間での相互運用性を確保するため、既定の CSP を使用するのではなく、このパラメーターを使用して CSP を明示的に設定してください。

dwProvType DWORD in 取得するプロバイダーの種類を指定します。定義済みのプロバイダーの種類については、Cryptographic Provider Types で説明しています。

dwFlags

DWORD

フラグ値。このパラメーターは通常 0 に設定しますが、アプリケーションによっては次のフラグを 1 つ以上設定します。

値	意味
CRYPT_VERIFYCONTEXT	このオプションは、一時的なキーを使用するアプリケーション、または永続化された秘密キーへのアクセスを必要としないアプリケーション (ハッシュ、暗号化、デジタル署名の検証のみを行うアプリケーションなど) を対象としています。秘密キーへのアクセスが必要なのは、署名を作成するアプリケーションまたはメッセージを復号するアプリケーションのみです。ほとんどの場合、このフラグを設定する必要があります。ファイルベースの CSP では、このフラグを設定する場合、szContainer パラメーターを NULL に設定する必要があります。アプリケーションは公開キー/秘密キーペアの永続化された秘密キーにアクセスできません。このフラグを設定すると、一時的な公開キー/秘密キーペアを作成できますが、永続化はされません。スマートカード CSP などのハードウェアベースの CSP では、szContainer パラメーターが NULL または空白の場合、このフラグはキーへのアクセスが不要であり、ユーザーに UI を表示すべきでないことを意味します。この形式は、CSP に接続してその機能を照会するために使用され、実際にキーを使用するためのものではありません。 szContainer パラメーターが NULL でも空白でもない場合、このフラグは、指定したコンテナー内の公開されている情報のみへのアクセスが必要であることを意味します。CSP は PIN を要求すべきではありません。秘密情報へのアクセス (たとえば CryptSignHash 関数) の試行は失敗します。 CryptAcquireContext を呼び出すとき、多くの CSP はキーコンテナー内の秘密キーへのアクセスを許可する前に、所有しているユーザーからの入力を必要とします。たとえば、秘密キーは暗号化されている場合があり、使用前にユーザーからのパスワードを必要とします。ただし、CRYPT_VERIFYCONTEXT フラグを指定した場合、秘密キーへのアクセスは不要であり、ユーザーインターフェイスをバイパスできます。
CRYPT_NEWKEYSET	szContainer で指定した名前で新しいキーコンテナーを作成します。szContainer が NULL の場合、既定の名前を持つキーコンテナーが作成されます。
CRYPT_MACHINE_KEYSET	既定では、キーとキーコンテナーはユーザーキーとして格納されます。Base Provider の場合、これはユーザーキーコンテナーがユーザーのプロファイルに格納されることを意味します。管理者がこのフラグなしで作成したキーコンテナーには、そのキーコンテナーを作成したユーザーと管理者権限を持つユーザーのみがアクセスできます。 Windows XP: 管理者がこのフラグなしで作成したキーコンテナーには、そのキーコンテナーを作成したユーザーとローカルシステムアカウントのみがアクセスできます。管理者ではないユーザーがこのフラグなしで作成したキーコンテナーには、そのキーコンテナーを作成したユーザーとローカルシステムアカウントのみがアクセスできます。 CRYPT_MACHINE_KEYSET フラグは、他のすべてのフラグと組み合わせて、対象のキーコンテナーがコンピューターキーコンテナーであり、CSP がそのように扱うことを示すことができます。Base Provider の場合、これはキーがそのキーコンテナーを作成したコンピューター上にローカルに格納されることを意味します。キーコンテナーをコンピューターコンテナーにする場合、そのコンピューターコンテナーを参照する CryptAcquireContext のすべての呼び出しで CRYPT_MACHINE_KEYSET フラグを使用する必要があります。管理者が CRYPT_MACHINE_KEYSET で作成したキーコンテナーには、 CryptSetProvParam を使用してコンテナーへのアクセス権が付与されていない限り、その作成者と管理者権限を持つユーザーのみがアクセスできます。 Windows XP: 管理者が CRYPT_MACHINE_KEYSET で作成したキーコンテナーには、 CryptSetProvParam を使用してコンテナーへのアクセス権が付与されていない限り、その作成者とローカルシステムアカウントのみがアクセスできます。管理者ではないユーザーが CRYPT_MACHINE_KEYSET で作成したキーコンテナーには、 CryptSetProvParam を使用してコンテナーへのアクセス権が付与されていない限り、その作成者とローカルシステムアカウントのみがアクセスできます。 CRYPT_MACHINE_KEYSET フラグは、対話的にログオンしなかったサービスまたはユーザーアカウントからユーザーがアクセスする場合に役立ちます。キーコンテナーを作成するとき、ほとんどの CSP は公開キー/秘密キーペアを自動的には作成しません。これらのキーは、 CryptGenKey 関数を使用して個別の手順として作成する必要があります。
CRYPT_DELETEKEYSET	szContainer で指定したキーコンテナーを削除します。szContainer が NULL の場合、既定の名前を持つキーコンテナーが削除されます。キーコンテナー内のすべてのキーペアも破棄されます。このフラグを設定すると、phProv に返される値は未定義となるため、後で CryptReleaseContext 関数を呼び出す必要はありません。
CRYPT_SILENT	アプリケーションは、このコンテキストに対して CSP がユーザーインターフェイス (UI) を一切表示しないよう要求します。CSP が動作するために UI を表示する必要がある場合、呼び出しは失敗し、NTE_SILENT_CONTEXT エラーコードが直前のエラーとして設定されます。さらに、CRYPT_SILENT フラグで取得したコンテキストに対して CRYPT_USER_PROTECTED フラグを指定して CryptGenKey を呼び出した場合、その呼び出しは失敗し、CSP は NTE_SILENT_CONTEXT を設定します。 CRYPT_SILENT は、CSP が UI を表示できないアプリケーションでの使用を目的としています。
CRYPT_DEFAULT_CONTAINER_OPTIONAL	ハッシュ処理と対称キー操作には使用できるが、PIN を使用したスマートカードへの認証が必要な操作には使用できないスマートカード CSP のコンテキストを取得します。この種類のコンテキストは、CryptSetProvParam を使用して PIN を設定するなど、空のスマートカードに対する操作を実行するために最もよく使用されます。このフラグはスマートカード CSP でのみ使用できます。 Windows Server 2003 および Windows XP: このフラグはサポートされていません。

戻り値の型: BOOL

公式ドキュメント

特定の暗号化サービスプロバイダー (CSP) 内の特定のキーコンテナーへのハンドルを取得するために使用します。返されたこのハンドルは、選択した CSP を使用する CryptoAPI 関数の呼び出しで使用されます。(ANSI)

戻り値

関数が成功すると、関数は 0 以外 (TRUE) を返します。

関数が失敗すると、0 (FALSE) を返します。拡張エラー情報を取得するには、GetLastError を呼び出します。

NTE で始まるエラーコードは、使用している特定の CSP によって生成されます。Winerror.h で定義されている可能性のあるエラーコードの一部を次に示します。

戻り値/値	説明
ERROR_BUSY 107L	一部の CSP は、CRYPT_DELETEKEYSET フラグ値が設定されていて、別のスレッドまたはプロセスがこのキーコンテナーを使用している場合に、このエラーを設定します。
ERROR_FILE_NOT_FOUND 2L	ユーザーのプロファイルが読み込まれておらず、見つかりません。これは、アプリケーションがユーザー (たとえば IUSR_ComputerName アカウント) になりすます場合に発生します。
ERROR_INVALID_PARAMETER 87L	いずれかのパラメーターに無効な値が含まれています。これは、ほとんどの場合、無効なポインターです。
ERROR_NOT_ENOUGH_MEMORY 8L	操作中にオペレーティングシステムのメモリが不足しました。
NTE_BAD_FLAGS 0x80090009L	dwFlags パラメーターに無効な値が指定されています。
NTE_BAD_KEY_STATE 0x8009000BL	秘密キーが暗号化されてから、ユーザーパスワードが変更されました。
NTE_BAD_KEYSET 0x80090016L	キーコンテナーを開けませんでした。このエラーの一般的な原因は、キーコンテナーが存在しないことです。キーコンテナーを作成するには、CRYPT_NEWKEYSET フラグを使用して CryptAcquireContext を呼び出します。このエラーコードは、既存のキーコンテナーへのアクセスが拒否されたことを示す場合もあります。コンテナーへのアクセス権は、キーセットの作成者が CryptSetProvParam を使用して付与できます。
NTE_BAD_KEYSET_PARAM 0x8009001FL	szContainer または szProvider パラメーターに無効な値が設定されています。
NTE_BAD_PROV_TYPE 0x80090014L	dwProvType パラメーターの値が範囲外です。すべてのプロバイダーの種類は 1 から 999 (両端を含む) の範囲でなければなりません。
NTE_BAD_SIGNATURE 0x80090006L	プロバイダー DLL の署名を検証できませんでした。DLL またはデジタル署名のいずれかが改ざんされています。
NTE_EXISTS 0x8009000FL	dwFlags パラメーターが CRYPT_NEWKEYSET ですが、キーコンテナーは既に存在しています。
NTE_KEYSET_ENTRY_BAD 0x8009001AL	szContainer キーコンテナーは見つかりましたが、破損しています。
NTE_KEYSET_NOT_DEF 0x80090019L	要求されたプロバイダーが存在しません。
NTE_NO_MEMORY 0x8009000EL	操作中に CSP のメモリが不足しました。
NTE_PROV_DLL_NOT_FOUND 0x8009001EL	プロバイダー DLL ファイルが存在しないか、現在のパス上にありません。
NTE_PROV_TYPE_ENTRY_BAD 0x80090018L	dwProvType で指定したプロバイダーの種類が破損しています。このエラーは、ユーザーの既定の CSP 一覧またはコンピューターの既定の CSP 一覧のいずれかに関連している可能性があります。
NTE_PROV_TYPE_NO_MATCH 0x8009001BL	dwProvType で指定したプロバイダーの種類が、見つかったプロバイダーの種類と一致しません。このエラーは、szProvider が実際の CSP 名を指定している場合にのみ発生する可能性があることに注意してください。
NTE_PROV_TYPE_NOT_DEF 0x80090017L	dwProvType で指定したプロバイダーの種類のエントリが存在しません。
NTE_PROVIDER_DLL_FAIL 0x8009001DL	プロバイダー DLL ファイルを読み込めなかったか、初期化に失敗しました。
NTE_SIGNATURE_FILE_BAD 0x8009001CL	DLL ファイルイメージの読み込み中、署名を検証する前にエラーが発生しました。

解説(Remarks)

szContainer パラメーターは、キーを保持するために使用するコンテナーの名前を指定します。各コンテナーには 1 つのキーを格納できます。キーの作成時に既存のコンテナーの名前を指定すると、新しいキーが以前のキーを上書きします。

CSP 名とキーコンテナー名の組み合わせにより、システム上の 1 つのキーが一意に識別されます。あるアプリケーションが別のアプリケーションの使用中にキーコンテナーを変更しようとすると、予測できない動作が発生する可能性があります。

szContainer パラメーターを NULL に設定すると、既定のキーコンテナー名が使用されます。この方法で Microsoft のソフトウェア CSP を呼び出すと、CryptAcquireContext 関数を呼び出すたびに新しいコンテナーが作成されます。ただし、CSP によってこの点での動作は異なる場合があります。特に、CSP が、その CSP にアクセスするすべてのアプリケーションで共有される単一の既定のコンテナーを持つ場合があります。したがって、アプリケーションは既定のキーコンテナーを使用して秘密キーを格納してはなりません。代わりに、dwFlags パラメーターに CRYPT_VERIFYCONTEXT フラグを渡してキーの格納を防止するか、他のアプリケーションで使用される可能性が低いアプリケーション固有のコンテナーを使用してください。

アプリケーションは、CryptGetProvParam 関数を使用して PP_CONTAINER 値を読み取ることにより、使用中のキーコンテナーの名前を取得できます。

パフォーマンス上の理由から、永続化されたキーが不要なすべての状況では、szContainer パラメーターを NULL に、dwFlags パラメーターを CRYPT_VERIFYCONTEXT に設定することをお勧めします。特に、次のシナリオでは、szContainer パラメーターを NULL に、dwFlags パラメーターを CRYPT_VERIFYCONTEXT に設定することを検討してください。

ハッシュを作成する場合。
データを暗号化または復号するための対称キーを生成する場合。
データを暗号化または復号するための対称キーをハッシュから導出する場合。
署名を検証する場合。CryptImportKey または CryptImportPublicKeyInfo を使用して、PUBLICKEYBLOB から、または証明書から公開キーをインポートできます。公開キーのインポートのみを行う予定の場合は、CRYPT_VERIFYCONTEXT フラグを使用してコンテキストを取得できます。
対称キーをエクスポートする予定だが、暗号コンテキストの有効期間内にインポートしない場合。最後の 2 つのシナリオで公開キーのインポートのみを行う予定の場合は、CRYPT_VERIFYCONTEXT フラグを使用してコンテキストを取得できます。
秘密キー操作を実行するが、キーコンテナーに格納された永続化された秘密キーを使用しない場合。

秘密キー操作を実行する予定の場合、コンテキストを取得する最善の方法は、コンテナーを開こうとすることです。この試行が NTE_BAD_KEYSET で失敗した場合は、CRYPT_NEWKEYSET フラグを使用してコンテナーを作成します。

例

次の例は、暗号コンテキストとキーコンテナー内の公開キー/秘密キーペアへのアクセスを取得する方法を示しています。要求されたキーコンテナーが存在しない場合は、作成されます。

この例の完全なコンテキストを含む例については、Example C Program: Creating a Key Container and Generating Keys を参照してください。その他の例については、Example C Program: Using CryptAcquireContext を参照してください。

//-------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hCryptProv = NULL;        // handle for a cryptographic
                                     // provider context
LPCSTR UserName = "MyKeyContainer";  // name of the key container
                                     // to be used
//-------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to zero
// to attempt to open an existing key container.

if(CryptAcquireContext(
   &hCryptProv,               // handle to the CSP
   UserName,                  // container name 
   NULL,                      // use the default provider
   PROV_RSA_FULL,             // provider type
   0))                        // flag values
{
    printf("A cryptographic context with the %s key container \n", 
  UserName);
    printf("has been acquired.\n\n");
}
else
{ 
//-------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key 
// container. Error codes are defined in Winerror.h.
 if (GetLastError() == NTE_BAD_KEYSET)
 {
   if(CryptAcquireContext(
      &hCryptProv, 
      UserName, 
      NULL, 
      PROV_RSA_FULL, 
      CRYPT_NEWKEYSET)) 
    {
      printf("A new key container has been created.\n");
    }
    else
    {
      printf("Could not create a new key container.\n");
      exit(1);
    }
  }
  else
  {
      printf("A cryptographic service handle could not be "
          "acquired.\n");
      exit(1);
   }
  
} // End of else.
//-------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a cryptographic provider handle.

//-------------------------------------------------------------------
// When the handle is no longer needed, it must be released.

if (CryptReleaseContext(hCryptProv,0))
{
  printf("The handle has been released.\n");
}
else
{
  printf("The handle could not be released.\n");
}

メモ

wincrypt.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして CryptAcquireContext を定義します。エンコーディング中立のエイリアスの使用を、エンコーディング中立でないコードと混在させると、不一致が生じ、コンパイルエラーまたは実行時エラーが発生する可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

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

各言語での呼び出し定義

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

BOOL CryptAcquireContextA(
    UINT_PTR* phProv,
    LPCSTR szContainer,   // optional
    LPCSTR szProvider,   // optional
    DWORD dwProvType,
    DWORD dwFlags
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern bool CryptAcquireContextA(
    out UIntPtr phProv,   // UINT_PTR* out
    [MarshalAs(UnmanagedType.LPStr)] string szContainer,   // LPCSTR optional
    [MarshalAs(UnmanagedType.LPStr)] string szProvider,   // LPCSTR optional
    uint dwProvType,   // DWORD
    uint dwFlags   // DWORD
);

<DllImport("ADVAPI32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CryptAcquireContextA(
    <Out> ByRef phProv As UIntPtr,   ' UINT_PTR* out
    <MarshalAs(UnmanagedType.LPStr)> szContainer As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> szProvider As String,   ' LPCSTR optional
    dwProvType As UInteger,   ' DWORD
    dwFlags As UInteger   ' DWORD
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' phProv : UINT_PTR* out
' szContainer : LPCSTR optional
' szProvider : LPCSTR optional
' dwProvType : DWORD
' dwFlags : DWORD
Declare PtrSafe Function CryptAcquireContextA Lib "advapi32" ( _
    ByRef phProv As LongPtr, _
    ByVal szContainer As String, _
    ByVal szProvider As String, _
    ByVal dwProvType 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

CryptAcquireContextA = ctypes.windll.advapi32.CryptAcquireContextA
CryptAcquireContextA.restype = wintypes.BOOL
CryptAcquireContextA.argtypes = [
    ctypes.POINTER(ctypes.c_size_t),  # phProv : UINT_PTR* out
    wintypes.LPCSTR,  # szContainer : LPCSTR optional
    wintypes.LPCSTR,  # szProvider : LPCSTR optional
    wintypes.DWORD,  # dwProvType : DWORD
    wintypes.DWORD,  # dwFlags : DWORD
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
CryptAcquireContextA = Fiddle::Function.new(
  lib['CryptAcquireContextA'],
  [
    Fiddle::TYPE_VOIDP,  # phProv : UINT_PTR* out
    Fiddle::TYPE_VOIDP,  # szContainer : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # szProvider : LPCSTR optional
    -Fiddle::TYPE_INT,  # dwProvType : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn CryptAcquireContextA(
        phProv: *mut usize,  // UINT_PTR* out
        szContainer: *const u8,  // LPCSTR optional
        szProvider: *const u8,  // LPCSTR optional
        dwProvType: u32,  // DWORD
        dwFlags: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern bool CryptAcquireContextA(out UIntPtr phProv, [MarshalAs(UnmanagedType.LPStr)] string szContainer, [MarshalAs(UnmanagedType.LPStr)] string szProvider, uint dwProvType, uint dwFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_CryptAcquireContextA' -Namespace Win32 -PassThru
# $api::CryptAcquireContextA(phProv, szContainer, szProvider, dwProvType, dwFlags)

#uselib "ADVAPI32.dll"
#func global CryptAcquireContextA "CryptAcquireContextA" sptr, sptr, sptr, sptr, sptr
; CryptAcquireContextA varptr(phProv), szContainer, szProvider, dwProvType, dwFlags   ; 戻り値は stat
; phProv : UINT_PTR* out -> "sptr"
; szContainer : LPCSTR optional -> "sptr"
; szProvider : LPCSTR optional -> "sptr"
; dwProvType : DWORD -> "sptr"
; dwFlags : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global CryptAcquireContextA "CryptAcquireContextA" var, str, str, int, int
; res = CryptAcquireContextA(phProv, szContainer, szProvider, dwProvType, dwFlags)
; phProv : UINT_PTR* out -> "var"
; szContainer : LPCSTR optional -> "str"
; szProvider : LPCSTR optional -> "str"
; dwProvType : DWORD -> "int"
; dwFlags : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global CryptAcquireContextA "CryptAcquireContextA" sptr, str, str, int, int
; res = CryptAcquireContextA(varptr(phProv), szContainer, szProvider, dwProvType, dwFlags)
; phProv : UINT_PTR* out -> "sptr"
; szContainer : LPCSTR optional -> "str"
; szProvider : LPCSTR optional -> "str"
; dwProvType : DWORD -> "int"
; dwFlags : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。