ホーム › Security.Cryptography › CryptRetrieveObjectByUrlA

CryptRetrieveObjectByUrlA

関数

URL(ANSI)から証明書やCRLなどの暗号オブジェクトを取得する。

DLLCRYPTNET.dll文字セットANSI (-A)呼出規約winapi対応OSWindows XP 以降

シグネチャ

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

BOOL CryptRetrieveObjectByUrlA(
    LPCSTR pszUrl,
    LPCSTR pszObjectOid,   // optional
    DWORD dwRetrievalFlags,
    DWORD dwTimeout,
    void** ppvObject,
    HCRYPTASYNC hAsyncRetrieve,   // optional
    CRYPT_CREDENTIALS* pCredentials,   // optional
    void* pvVerify,   // optional
    CRYPT_RETRIEVE_AUX_INFO* pAuxInfo   // optional
);

パラメーター

名前型方向説明

pszUrl

LPCSTR

取得する PKI オブジェクトのアドレス。次のスキームがサポートされます。

ldap (Lightweight Directory Access Protocol)
http
https (証明書失効リスト (CRL) またはオンライン証明書状態プロトコル (OCSP) の取得のみ)
file

pszObjectOid

LPCSTR

inoptional

取得するオブジェクトの種類を識別する、null で終わる ANSI 文字列のアドレス。次のいずれかの値を指定できます。

値	意味
NULL BLOB	1 つ以上のデータ BLOB を取得します。エンコードされたビットは BLOB の配列として返されます。ppvObject は、BLOB 配列を受け取る CRYPT_BLOB_ARRAY 構造体ポインターのアドレスです。この構造体が不要になったら、その構造体のアドレスを CryptMemFree 関数に渡して解放する必要があります。
CONTEXT_OID_CERTIFICATE certificate	1 つ以上の証明書を取得します。単一のオブジェクトを取得する場合、ppvObject はコンテキストを受け取る CERT_CONTEXT 構造体ポインターのアドレスです。このコンテキストが不要になったら、CERT_CONTEXT 構造体ポインターを CertFreeCertificateContext 関数に渡して解放する必要があります。複数のオブジェクトを取得する場合、ppvObject は、証明書を格納するストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。
CONTEXT_OID_CRL CRL	1 つ以上の証明書失効リスト (CRL) を取得します。単一のオブジェクトを取得する場合、ppvObject はコンテキストを受け取る CRL_CONTEXT 構造体ポインターのアドレスです。このコンテキストが不要になったら、CRL_CONTEXT 構造体ポインターを CertFreeCRLContext 関数に渡して解放する必要があります。複数のオブジェクトを取得する場合、ppvObject は、CRL を格納するストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。
CONTEXT_OID_CTL CTL	1 つ以上の証明書信頼リスト (CTL) を取得します。単一のオブジェクトを取得する場合、ppvObject はコンテキストを受け取る CTL_CONTEXT 構造体ポインターのアドレスです。このコンテキストが不要になったら、CTL_CONTEXT 構造体ポインターを CertFreeCTLContext 関数に渡して解放する必要があります。複数のオブジェクトを取得する場合、ppvObject は、CTL を格納するストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。
CONTEXT_OID_PKCS7 PKCS7	ppvObject は、メッセージ内のオブジェクトを格納するストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。
CONTEXT_OID_CAPI2_ANY 関数が適切な項目を判別します	ppvObject は、オブジェクトを格納するストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。
CONTEXT_OID_OCSP_RESP OCSP 応答	ppvObject は、CRYPT_BLOB_ARRAY 構造体へのポインターのアドレスです。

dwRetrievalFlags

DWORD

キャッシュされた URL を使用するか、ワイヤー URL から取得した URL を使用するかを決定します。オブジェクトが返される形式は pszObjectOid の値によって決まります。

値	意味
CRYPT_AIA_RETRIEVAL	ワイヤー URL によって取得されたコンテンツを、その URL をキャッシュに書き込む前に検証します。既定のプロバイダーは、AIA 取得での HTTPS プロトコルをサポートしません。
CRYPT_ASYNC_RETRIEVAL	この値はサポートされていません。
CRYPT_CACHE_ONLY_RETRIEVAL	エンコードされたビットを URL キャッシュからのみ取得します。URL の取得にワイヤーを使用しません。
CRYPT_DONT_CACHE_RESULT	取得したエンコード済みビットを URL キャッシュに保存しません。このフラグが設定されていない場合、取得した URL はキャッシュされます。
CRYPT_HTTP_POST_RETRIEVAL	HTTP 取得において、既定の GET メソッドの代わりに POST メソッドを使用します。 POST URL では、追加のバイナリデータとヘッダー文字列が次の形式でベース URL に付加されます。 BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders 次の例は、最後のスラッシュ (/) で区切られた追加のバイナリデータと、疑問符 (?) で区切られた Content-Type ヘッダーがベース URL に付加された様子を示しています。 `http://ocsp.openvalidation.org/MEIwQDA%2BMDwwOjAJBgUrDgMCGgUABBQdKNEwjytjKBQADcgM61jfflNpyQQUv1NDgnjQnsOA5RtnygUA37lIg6UCAQI%3D?Content-Type: application/ocsp-request` このフラグが設定されている場合、CryptRetrieveObjectByUrl 関数は、最後のスラッシュ (/) と疑問符 (?) を区切り文字として URL を解析します。スラッシュ (/) で区切られた文字列には、エスケープされていない URL (つまり、エスケープ文字やエスケープシーケンスを含まないプレーンテキストの URL) と、バイナリ形式にデコードされた Base64 データが含まれ、WinHttpSendRequest 関数に lpOptional パラメーターとして渡される前に処理されます。疑問符 (?) で区切られた文字列は、WinHttpSendRequest 関数に pwszHeaders パラメーターとして渡されます。
CRYPT_LDAP_AREC_EXCLUSIVE_RETRIEVAL	指定されたホスト文字列に対して A レコードのみの DNS ルックアップを実行し、ホスト名の解決時に誤った DNS クエリが生成されるのを防ぎます。このフラグは、ドメイン名ではなくホスト名を渡す場合に使用してください。
CRYPT_LDAP_INSERT_ENTRY_ATTRIBUTE	各 LDAP オブジェクトのエントリインデックスと属性名を取得します。返される各 BLOB の先頭には、次の ANSI 文字列が含まれます。 "10 進数のエントリインデックス\0属性名\0" このフラグが設定されている場合、BLOB が返されるように pszObjectOid は NULL でなければなりません。このフラグは ldap スキームにのみ適用されます。
CRYPT_LDAP_SCOPE_BASE_ONLY_RETRIEVAL	URL 内で LDAP の検索スコープが base に設定されていない場合は失敗します。LDAP でのみ使用します。
CRYPT_LDAP_SIGN_RETRIEVAL	Kerberos 認証プロトコルを使用して、サーバーとの間で送受信されるすべての LDAP トラフィックにデジタル署名します。この機能は、一部のアプリケーションで必要とされる整合性を提供します。
CRYPT_NO_AUTH_RETRIEVAL	自動認証処理を抑制します。
CRYPT_NOT_MODIFIED_RETRIEVAL	条件付き HTTP URL 取得を有効にします。このフラグが設定されている場合、HTTP_STATUS_NOT_MODIFIED を返す条件付き取得では、CryptRetrieveObjectByUrl は TRUE を返し、ppvObject は NULL に設定されます。pAuxInfo が NULL でない場合、dwHttpStatusCode は HTTP_STATUS_NOT_MODIFIED に設定されます。それ以外の場合、取得が成功すると ppvObject が更新されます。
CRYPT_OFFLINE_CHECK_RETRIEVAL	オフライン時の失敗を記録し、以降の取得でワイヤーにアクセスする前に遅延を設けます。この値はワイヤー取得にのみ適用されます。
CRYPT_PROXY_CACHE_RETRIEVAL	オブジェクトのプロキシキャッシュ取得を有効にします。プロキシキャッシュが明示的にバイパスされなかった場合、pAuxInfo の fProxyCacheRetrieval が TRUE に設定されます。この値は HTTP URL の取得にのみ適用されます。
CRYPT_RETRIEVE_MULTIPLE_OBJECTS	利用可能であれば複数のオブジェクトを取得します。オブジェクト識別子 (OID) の値が CONTEXT_OID_CAPI2_ANY の場合を除き、すべてのオブジェクトは pszObjectOid の値によって決まる同一のオブジェクト型でなければなりません。
CRYPT_STICKY_CACHE_RETRIEVAL	URL をキャッシュからフラッシュされない対象としてタグ付けします。詳細については、INTERNET_CACHE_ENTRY_INFO の STICKY_CACHE_ENTRY を参照してください。
CRYPT_VERIFY_CONTEXT_SIGNATURE	作成されたコンテキストに対して署名検証を取得します。この場合、pszObjectOid は非 NULL でなければならず、pvVerify は署名者の証明書コンテキストを指します。
CRYPT_VERIFY_DATA_HASH	このフラグは実装されていません。使用しないでください。
CRYPT_WIRE_ONLY_RETRIEVAL	エンコードされたビットをワイヤーからのみ取得します。URL キャッシュは使用しません。

dwTimeout DWORD in 取得を待機する最大ミリ秒数を指定します。値に 0 を指定した場合、この関数はタイムアウトしません。URL スキームが file:/// の場合、このパラメーターは使用されません。

ppvObject void** out 返されるオブジェクトへのポインターのアドレス。戻り値の型は、pszObjectOid に示されたサポート対象の型のいずれかになります。

hAsyncRetrieve HCRYPTASYNC inoptional このパラメーターは予約されており、NULL に設定する必要があります。

pCredentials CRYPT_CREDENTIALS* inoptional このパラメーターは使用されません。

pvVerify void* inoptional 検証オブジェクトへのポインター。このオブジェクトは dwRetrievalFlags パラメーターに応じて変化します。dwRetrievalFlags が CRYPT_VERIFY_CONTEXT_SIGNATURE の場合に、呼び出し元が署名者の証明書コンテキストやインデックスの取得を必要としないことを示すために NULL にすることができます。

pAuxInfo CRYPT_RETRIEVE_AUX_INFO* inoutoptional CRYPT_RETRIEVE_AUX_INFO 構造体への省略可能なポインター。NULL でなく、かつ構造体の cbSize メンバーが設定されている場合、このパラメーターは最後に成功したワイヤー取得の時刻を返します。

戻り値の型: BOOL

公式ドキュメント

URL で指定された場所から公開鍵基盤 (PKI) オブジェクトを取得します。(ANSI)

戻り値

関数が成功した場合、戻り値は 0 以外 (TRUE) です。

関数が失敗した場合、戻り値は 0 (FALSE) です。

解説(Remarks)

リモートオブジェクト取得マネージャーは 2 つのプロバイダーモデルを公開します。1 つはスキームプロバイダーモデルで、URL スキーム (ldap、http、ftp、file) によって定義されるインストール可能なプロトコルプロバイダーを利用できます。スキームプロバイダーのエントリポイントは CryptRetrieveObjectByUrl 関数と同じですが、返される *ppvObject は常にエンコードされたビットのカウント付き配列 (取得されたオブジェクトごとに 1 つ) です。

2 つ目のプロバイダーモデルはコンテキストプロバイダーモデルで、取得されたエンコード済みビットに基づいてコンテキストハンドル (オブジェクト) を生成する、インストール可能な生成元を利用できます。これらは CryptRetrieveObjectByUrl の呼び出しで指定されたオブジェクト識別子 (OID) に基づいてディスパッチされます。

証明書、信頼リスト、失効リスト、PKCS #7 メッセージなどの個々の PKI オブジェクト、および複数の同種オブジェクトを取得できます。Windows Vista with Service Pack 1 (SP1) および Windows Server 2008 以降では、"http:" および "ldap:" 取得のセキュリティが強化されています。この関数は、"http:" および "ldap:" の URL スキームに加え、新たに定義されたスキームをサポートします。

Windows XP: ネットワーク取得において "ftp:" はサポートされません。

注意既定では、ネットワーク取得において "file:" はサポートされません。

メモ

wincrypt.h ヘッダーは CryptRetrieveObjectByUrl を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義します。エンコードニュートラルなエイリアスの使用と、エンコードニュートラルでないコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因となることがあります。詳細については、関数プロトタイプの規約を参照してください。

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

各言語での呼び出し定義

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

BOOL CryptRetrieveObjectByUrlA(
    LPCSTR pszUrl,
    LPCSTR pszObjectOid,   // optional
    DWORD dwRetrievalFlags,
    DWORD dwTimeout,
    void** ppvObject,
    HCRYPTASYNC hAsyncRetrieve,   // optional
    CRYPT_CREDENTIALS* pCredentials,   // optional
    void* pvVerify,   // optional
    CRYPT_RETRIEVE_AUX_INFO* pAuxInfo   // optional
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPTNET.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern bool CryptRetrieveObjectByUrlA(
    [MarshalAs(UnmanagedType.LPStr)] string pszUrl,   // LPCSTR
    [MarshalAs(UnmanagedType.LPStr)] string pszObjectOid,   // LPCSTR optional
    uint dwRetrievalFlags,   // DWORD
    uint dwTimeout,   // DWORD
    IntPtr ppvObject,   // void** out
    IntPtr hAsyncRetrieve,   // HCRYPTASYNC optional
    IntPtr pCredentials,   // CRYPT_CREDENTIALS* optional
    IntPtr pvVerify,   // void* optional
    IntPtr pAuxInfo   // CRYPT_RETRIEVE_AUX_INFO* optional, in/out
);

<DllImport("CRYPTNET.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function CryptRetrieveObjectByUrlA(
    <MarshalAs(UnmanagedType.LPStr)> pszUrl As String,   ' LPCSTR
    <MarshalAs(UnmanagedType.LPStr)> pszObjectOid As String,   ' LPCSTR optional
    dwRetrievalFlags As UInteger,   ' DWORD
    dwTimeout As UInteger,   ' DWORD
    ppvObject As IntPtr,   ' void** out
    hAsyncRetrieve As IntPtr,   ' HCRYPTASYNC optional
    pCredentials As IntPtr,   ' CRYPT_CREDENTIALS* optional
    pvVerify As IntPtr,   ' void* optional
    pAuxInfo As IntPtr   ' CRYPT_RETRIEVE_AUX_INFO* optional, in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' pszUrl : LPCSTR
' pszObjectOid : LPCSTR optional
' dwRetrievalFlags : DWORD
' dwTimeout : DWORD
' ppvObject : void** out
' hAsyncRetrieve : HCRYPTASYNC optional
' pCredentials : CRYPT_CREDENTIALS* optional
' pvVerify : void* optional
' pAuxInfo : CRYPT_RETRIEVE_AUX_INFO* optional, in/out
Declare PtrSafe Function CryptRetrieveObjectByUrlA Lib "cryptnet" ( _
    ByVal pszUrl As String, _
    ByVal pszObjectOid As String, _
    ByVal dwRetrievalFlags As Long, _
    ByVal dwTimeout As Long, _
    ByVal ppvObject As LongPtr, _
    ByVal hAsyncRetrieve As LongPtr, _
    ByVal pCredentials As LongPtr, _
    ByVal pvVerify As LongPtr, _
    ByVal pAuxInfo As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CryptRetrieveObjectByUrlA = ctypes.windll.cryptnet.CryptRetrieveObjectByUrlA
CryptRetrieveObjectByUrlA.restype = wintypes.BOOL
CryptRetrieveObjectByUrlA.argtypes = [
    wintypes.LPCSTR,  # pszUrl : LPCSTR
    wintypes.LPCSTR,  # pszObjectOid : LPCSTR optional
    wintypes.DWORD,  # dwRetrievalFlags : DWORD
    wintypes.DWORD,  # dwTimeout : DWORD
    ctypes.c_void_p,  # ppvObject : void** out
    ctypes.c_ssize_t,  # hAsyncRetrieve : HCRYPTASYNC optional
    ctypes.c_void_p,  # pCredentials : CRYPT_CREDENTIALS* optional
    ctypes.POINTER(None),  # pvVerify : void* optional
    ctypes.c_void_p,  # pAuxInfo : CRYPT_RETRIEVE_AUX_INFO* optional, in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('CRYPTNET.dll')
CryptRetrieveObjectByUrlA = Fiddle::Function.new(
  lib['CryptRetrieveObjectByUrlA'],
  [
    Fiddle::TYPE_VOIDP,  # pszUrl : LPCSTR
    Fiddle::TYPE_VOIDP,  # pszObjectOid : LPCSTR optional
    -Fiddle::TYPE_INT,  # dwRetrievalFlags : DWORD
    -Fiddle::TYPE_INT,  # dwTimeout : DWORD
    Fiddle::TYPE_VOIDP,  # ppvObject : void** out
    Fiddle::TYPE_INTPTR_T,  # hAsyncRetrieve : HCRYPTASYNC optional
    Fiddle::TYPE_VOIDP,  # pCredentials : CRYPT_CREDENTIALS* optional
    Fiddle::TYPE_VOIDP,  # pvVerify : void* optional
    Fiddle::TYPE_VOIDP,  # pAuxInfo : CRYPT_RETRIEVE_AUX_INFO* optional, in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "cryptnet")]
extern "system" {
    fn CryptRetrieveObjectByUrlA(
        pszUrl: *const u8,  // LPCSTR
        pszObjectOid: *const u8,  // LPCSTR optional
        dwRetrievalFlags: u32,  // DWORD
        dwTimeout: u32,  // DWORD
        ppvObject: *mut *mut (),  // void** out
        hAsyncRetrieve: isize,  // HCRYPTASYNC optional
        pCredentials: *mut CRYPT_CREDENTIALS,  // CRYPT_CREDENTIALS* optional
        pvVerify: *mut (),  // void* optional
        pAuxInfo: *mut CRYPT_RETRIEVE_AUX_INFO  // CRYPT_RETRIEVE_AUX_INFO* optional, in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("CRYPTNET.dll", CharSet = CharSet.Ansi)]
public static extern bool CryptRetrieveObjectByUrlA([MarshalAs(UnmanagedType.LPStr)] string pszUrl, [MarshalAs(UnmanagedType.LPStr)] string pszObjectOid, uint dwRetrievalFlags, uint dwTimeout, IntPtr ppvObject, IntPtr hAsyncRetrieve, IntPtr pCredentials, IntPtr pvVerify, IntPtr pAuxInfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'CRYPTNET_CryptRetrieveObjectByUrlA' -Namespace Win32 -PassThru
# $api::CryptRetrieveObjectByUrlA(pszUrl, pszObjectOid, dwRetrievalFlags, dwTimeout, ppvObject, hAsyncRetrieve, pCredentials, pvVerify, pAuxInfo)

#uselib "CRYPTNET.dll"
#func global CryptRetrieveObjectByUrlA "CryptRetrieveObjectByUrlA" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; CryptRetrieveObjectByUrlA pszUrl, pszObjectOid, dwRetrievalFlags, dwTimeout, ppvObject, hAsyncRetrieve, varptr(pCredentials), pvVerify, varptr(pAuxInfo)   ; 戻り値は stat
; pszUrl : LPCSTR -> "sptr"
; pszObjectOid : LPCSTR optional -> "sptr"
; dwRetrievalFlags : DWORD -> "sptr"
; dwTimeout : DWORD -> "sptr"
; ppvObject : void** out -> "sptr"
; hAsyncRetrieve : HCRYPTASYNC optional -> "sptr"
; pCredentials : CRYPT_CREDENTIALS* optional -> "sptr"
; pvVerify : void* optional -> "sptr"
; pAuxInfo : CRYPT_RETRIEVE_AUX_INFO* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "CRYPTNET.dll"
#cfunc global CryptRetrieveObjectByUrlA "CryptRetrieveObjectByUrlA" str, str, int, int, sptr, sptr, var, sptr, var
; res = CryptRetrieveObjectByUrlA(pszUrl, pszObjectOid, dwRetrievalFlags, dwTimeout, ppvObject, hAsyncRetrieve, pCredentials, pvVerify, pAuxInfo)
; pszUrl : LPCSTR -> "str"
; pszObjectOid : LPCSTR optional -> "str"
; dwRetrievalFlags : DWORD -> "int"
; dwTimeout : DWORD -> "int"
; ppvObject : void** out -> "sptr"
; hAsyncRetrieve : HCRYPTASYNC optional -> "sptr"
; pCredentials : CRYPT_CREDENTIALS* optional -> "var"
; pvVerify : void* optional -> "sptr"
; pAuxInfo : CRYPT_RETRIEVE_AUX_INFO* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "CRYPTNET.dll"
#cfunc global CryptRetrieveObjectByUrlA "CryptRetrieveObjectByUrlA" str, str, int, int, sptr, sptr, sptr, sptr, sptr
; res = CryptRetrieveObjectByUrlA(pszUrl, pszObjectOid, dwRetrievalFlags, dwTimeout, ppvObject, hAsyncRetrieve, varptr(pCredentials), pvVerify, varptr(pAuxInfo))
; pszUrl : LPCSTR -> "str"
; pszObjectOid : LPCSTR optional -> "str"
; dwRetrievalFlags : DWORD -> "int"
; dwTimeout : DWORD -> "int"
; ppvObject : void** out -> "sptr"
; hAsyncRetrieve : HCRYPTASYNC optional -> "sptr"
; pCredentials : CRYPT_CREDENTIALS* optional -> "sptr"
; pvVerify : void* optional -> "sptr"
; pAuxInfo : CRYPT_RETRIEVE_AUX_INFO* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。