CryptRetrieveObjectByUrlW 関数 (wincrypt.h)
CryptRetrieveObjectByUrl 関数は、URL で指定された場所から公開キー 基盤 (PKI) オブジェクトを取得します。
これらのリモート オブジェクトはエンコードされた形式であり、"コンテキスト" 形式で取得されます。
構文
BOOL CryptRetrieveObjectByUrlW(
[in] LPCWSTR pszUrl,
[in] LPCSTR pszObjectOid,
[in] DWORD dwRetrievalFlags,
[in] DWORD dwTimeout,
[out] LPVOID *ppvObject,
[in] HCRYPTASYNC hAsyncRetrieve,
[in, optional] PCRYPT_CREDENTIALS pCredentials,
[in, optional] LPVOID pvVerify,
[in] PCRYPT_RETRIEVE_AUX_INFO pAuxInfo
);
パラメーター
[in] pszUrl
取得する PKI オブジェクトのアドレス。 次のスキームがサポートされています。
- ldap (ライトウェイト ディレクトリ アクセス プロトコル)
- http
- https (証明書失効リスト (CRL) または オンライン証明書状態プロトコル (OCSP) の取得のみ)
- file
[in] pszObjectOid
取得するオブジェクトの種類を識別する null で終わる ANSI 文字列のアドレス。 次のいずれかの値を指定できます。
| 値 | 意味 |
|---|---|
|
1 つ以上のデータ BLOB を取得します。 エンコードされたビットは BLOB の配列で返されます。 ppvObject は、BLOB 配列を受け取 るCRYPT_BLOB_ARRAY 構造体ポインターのアドレスです。 この構造体が不要になったら、この構造体のアドレスを CryptMemFree 関数に渡して解放する必要があります。 |
|
1 つ以上の証明書を取得します。
単一のオブジェクトが取得されている場合、 ppvObject はコンテキストを受け取る CERT_CONTEXT 構造体ポインターのアドレスです。 このコンテキストが不要になったら、 CERT_CONTEXT 構造体ポインターを CertFreeCertificateContext 関数に渡して解放する必要があります。 複数のオブジェクトが取得されている場合、 ppvObject は、証明書を含むストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。 |
|
1 つ以上の 証明書失効リスト (CRL) を取得します。
単一のオブジェクトが取得されている場合、 ppvObject はコンテキストを受け取 るCRL_CONTEXT 構造体ポインターのアドレスです。 このコンテキストが不要になった場合は、 CRL_CONTEXT 構造体ポインターを CertFreeCRLContext 関数に渡して解放する必要があります。 複数のオブジェクトが取得されている場合、 ppvObject は CRL を含むストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。 |
|
1 つ以上の 証明書信頼リスト (CCTL) を取得します。
単一のオブジェクトが取得されている場合、 ppvObject はコンテキストを受け取る CTL_CONTEXT 構造体ポインターのアドレスです。 このコンテキストが不要になったら、 CTL_CONTEXT 構造体ポインターを CertFreeCTLContext 関数に渡して解放する必要があります。 複数のオブジェクトが取得されている場合、 ppvObject は、CCTL を含むストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。 |
|
ppvObject は、メッセージからオブジェクトを含むストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。 |
|
ppvObject は、オブジェクトを含むストアのハンドルを受け取る HCERTSTORE 変数のアドレスです。 このストアが不要になったら、このハンドルを CertCloseStore 関数に渡して閉じる必要があります。 |
|
ppvObject は、 CRYPT_BLOB_ARRAY 構造体へのポインターのアドレスです。 |
[in] dwRetrievalFlags
キャッシュされた URL を使用するか、ワイヤ URL から取得した URL を使用するかを決定します。 オブジェクトが返されるフォームは、 pszObjectOid の値によって決まります。
| 値 | 意味 |
|---|---|
|
URL をキャッシュに書き込む前に、ワイヤ URL によって取得されたコンテンツを検証します。
既定のプロバイダーでは、AIA 取得用の HTTPS プロトコルはサポートされていません。 |
|
この値はサポートされていません。 |
|
URL キャッシュからのみエンコードされたビットを取得します。 ワイヤを使用して URL を取得しないでください。 |
|
取得したエンコードされたビットを URL キャッシュに格納しません。 このフラグが設定されていない場合は、取得した URL がキャッシュされます。 |
|
HTTP 取得に既定の GET メソッドの代わりに POST メソッドを使用します。
POST URL では、追加のバイナリ データとヘッダー文字列が、次の形式でベース URL に追加されます。 BaseURL/OptionalURLEscaped&Base64EncodedAdditionalData?OptionalAdditionalHTTPHeaders 次の例は、最後のスラッシュ (/) で区切られた追加のバイナリ データと、ベース URL に付加された疑問符 (?) で区切られた Content-Type ヘッダーを示しています。
このフラグを設定すると、 CryptRetrieveObjectByUrl 関数は最後のスラッシュ (/) 区切り記号と疑問符 (?) 区切り記号を使用して URL を解析します。 スラッシュ (/) で区切られた文字列には、エスケープされていない URL (つまり、エスケープ文字やエスケープ シーケンスのないプレーン テキスト URL) と、バイナリ形式でデコードされた Base64 データが含まれます。その後、lpOptional パラメーターとして WinHttpSendRequest 関数に渡されます。 疑問符 (?) で区切られた文字列は、pwszHeaders パラメーターとして WinHttpSendRequest 関数に渡されます。 |
|
指定されたホスト文字列に対して A レコードのみの DNS 参照を実行し、ホスト名を解決するときに偽の DNS クエリが生成されないようにします。 このフラグは、ドメイン名ではなくホスト名を渡すときに使用する必要があります。 |
|
各 LDAP オブジェクトのエントリ インデックスと属性名を取得します。 返される各 BLOB の先頭には、次の ANSI 文字列が含まれています。 "decimal\0属性名\0 のエントリ インデックス" このフラグが設定されている場合、BLOB が返されるように pszObjectOid は NULL である必要があります。 このフラグは ldap スキームにのみ適用されます。 |
|
LDAP 検索スコープが URL のベースに設定されていない場合、失敗します。 LDAP でのみを使用します。 |
|
Kerberos 認証プロトコルを使用して、サーバーとの間のすべての LDAP トラフィックにデジタル署名します。 この機能は、一部のアプリケーションで必要な整合性を提供します。 |
|
自動認証処理を禁止します。 |
|
条件付き HTTP URL の取得を有効にします。 このフラグが設定されている場合、 HTTP_STATUS_NOT_MODIFIEDを返す条件付き取得の 場合、CryptRetrieveObjectByUrl は TRUE を 返し、 ppvObject は NULL に設定されます。 pAuxInfo が NULL でない場合、dwHttpStatusCode はHTTP_STATUS_NOT_MODIFIEDに設定されます。 それ以外の場合、 ppvObject は正常に取得するために更新されます。 |
|
後続の取得時にネットワークに到達する前に、オフラインの障害と遅延を追跡します。 この値は、ワイヤ取得専用です。 |
|
オブジェクトのプロキシ キャッシュ取得を有効にします。 プロキシ キャッシュが明示的にバイパスされなかった場合、pAuxInfo では fProxyCacheRetrieval が TRUE に設定されます。 この値は、HTTP URL の取得にのみ適用されます。 |
|
使用可能な場合は、複数のオブジェクトを取得します。 オブジェクト識別子 (OID) の値がCONTEXT_OID_CAPI2_ANYされていない限り、 pszObjectOid の値によって決定される、すべてのオブジェクトは同種 のオブジェクト 型である必要があります。 |
|
キャッシュからフラッシュされないように URL にタグを付けます。 詳細については、「INTERNET_CACHE_ENTRY_INFOのSTICKY_CACHE_ENTRY」を参照してください。 |
|
作成されたコンテキストで署名検証を取得します。 この場合 、pszObjectOid は NULL 以外である必要があり、 pvVerify は署名者証明書コンテキストを指します。 |
|
このフラグは実装されていません。 使用しないでください。 |
|
ワイヤからのみエンコードされたビットを取得します。 URL キャッシュを使用しません。 |
[in] dwTimeout
取得を待機する最大ミリ秒数を指定します。 0 の値を指定した場合、この関数はタイムアウトしません。URL スキームが file:/// されている場合、このパラメーターは使用されません。
[out] ppvObject
返されるオブジェクトへのポインターのアドレス。 戻り値の型には、 pszObjectOid でサポートされている型のいずれかを指定できます。
[in] hAsyncRetrieve
このパラメーターは予約済みであり、 NULL に設定する必要があります。
[in, optional] pCredentials
このパラメーターは使用されません。
[in, optional] pvVerify
検証オブジェクトへのポインター。 このオブジェクトは dwRetrievalFlags パラメーターの 関数です。 dwRetrievalFlags がCRYPT_VERIFY_CONTEXT_SIGNATUREされている場合、呼び出し元が署名者の証明書コンテキストまたはインデックスの取得に関心を持たないことを示すには、NULL を指定できます。
[in] pAuxInfo
CRYPT_RETRIEVE_AUX_INFO構造体への省略可能なポインター。 NULL でない場合、および構造体の cbSize メンバーが設定されている場合、このパラメーターは最後に正常にワイヤ取得が成功した時刻を返します。
戻り値
関数が成功した場合、戻り値は 0 以外 (TRUE) になります。
関数が失敗した場合、戻り値は 0 (FALSE) になります。
注釈
リモート オブジェクト取得マネージャーは、2 つのプロバイダー モデルを公開します。 1 つは、URL スキームによって定義されたインストール可能なプロトコル プロバイダー (ldap、http、ftp、またはファイル) を可能にするスキーム プロバイダー モデルです。 スキーム プロバイダーのエントリ ポイントは、 CryptRetrieveObjectByUrl 関数と同じです。ただし、返される *ppvObject は常に、エンコードされたビット (取得されたオブジェクトごとに 1 つ) のカウントされた配列です。
2 番目のプロバイダー モデルはコンテキスト プロバイダー モデルであり、取得したエンコードされたビットに基づいてコンテキスト ハンドル (オブジェクト) のインストール可能な作成者を許可します。 これらは、CryptRetrieveObjectByUrl の呼び出しで指定されたオブジェクト識別子 (OID) に基づいてディスパッチされます。
証明書、信頼リスト、失効リスト、PKCS #7 メッセージ、複数の同種オブジェクトなどの個々の PKI オブジェクトを取得できます。 Windows Vista Service Pack 1 (SP1) および Windows Server 2008 以降では、"http:" と "ldap:" の取得のセキュリティが強化されています。
この関数は、"http:" および "ldap:" URL スキームと、新しく定義されたスキームをサポートします。
Windows XP: "ftp:" はネットワーク取得ではサポートされていません。
注意
wincrypt.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CryptRetrieveObjectByUrl を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Cryptnet.lib |
| [DLL] | Cryptnet.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示