IBackgroundCopyJobHttpOptions::SetClientCertificateByID メソッド (bits2_5.h)

HTTPS (SSL) 要求でのクライアント認証に使用するクライアント証明書の識別子を指定します。

構文

HRESULT SetClientCertificateByID(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] byte                   *pCertHashBlob
);

パラメーター

[in] StoreLocation

証明書の参照に使用するシステム ストアの場所を識別します。 使用できる値については、 BG_CERT_STORE_LOCATION 列挙を参照してください。

[in] StoreName

証明書ストアの名前を含む Null で終わる文字列。 文字列は、null 終端記号を含め、256 文字に制限されています。 次のいずれかのシステム ストアまたはアプリケーション定義ストアを指定できます。 ストアには、ローカル ストアまたはリモート ストアを指定できます。

意味
Ca
証明機関の証明書
私の
個人用証明書
ルート
ルート証明書
Spc
ソフトウェア発行元証明書

[in] pCertHashBlob

証明書を識別する SHA1 ハッシュ。 ハッシュには 20 バイトのバッファーを使用します。 詳細については、「解説」を参照してください。

戻り値

次の表に、可能な戻り値の一部を示します。

リターン コード 説明
S_OK
正常終了しました。
E_ACCESSDENIED
ユーザーには、ストアの場所にアクセスするためのアクセス許可がありません。
E_NOTIMPL
StoreLocation パラメーターの値は、BG_CERT_STORE_LOCATION列挙では定義されていません。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
StoreName パラメーターと一致するストアが見つかりませんでした。
CRYPT_E_NOT_FOUND
ハッシュに一致する証明書が見つかりませんでした。
RPC_X_NULL_REF_POINTER
StoreName または pCertHashBlob パラメーターを NULL にすることはできません。
RPC_X_BAD_STUB_DATA
pCertHashBlob バッファー サイズが 20 バイトではありません。
BG_E_STRING_TOO_LONG
StoreName パラメーターは 256 文字を超えています。
BG_E_INVALID_STATE
ジョブの状態をBG_JOB_STATE_CANCELLEDまたはBG_JOB_STATE_ACKNOWLEDGEDすることはできません。

注釈

クライアント証明書を指定できるのは、ジョブ所有者だけです。 ジョブが所有権を変更した場合、BITS はジョブから証明書を削除します。

クライアント証明書は、HTTP または HTTPS プロトコルを使用するリモート ファイルにのみ適用されます。 すべてのジョブの種類に証明書を指定できます。

Web サイトが SSL クライアント証明書を受け入れるが不要で、BITS ジョブでクライアント証明書が指定されていない場合、ジョブは ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c) で失敗します。

ジョブまたはアプリケーションの証明書を作成する場合は、レジストリまたはデータベースに証明書識別子 (拇印) を格納し、ジョブで証明書が必要な場合に使用できます。 ストア内の証明書を列挙し、ユーザーが証明書を選択できるようにすることもできます。 もう 1 つの方法は、 CertFindCertificateInStore 関数を呼び出して、いくつかの条件に基づいて証明書コンテキストを取得することです。 コンテキストを使用して 、CertGetCertificateContextProperty 関数を呼び出してハッシュを取得します ( dwPropId のCERT_HASH_PROP_IDを指定します)。

SmartCard の拇印はサポートされていません。

次の例は、証明書の拇印を使用してジョブのクライアント証明書を指定する方法を示しています。 この例では、証明書の拇印をハードコードし、pJob が有効なジョブを指していることを前提としています。


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;  
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;
  BYTE Thumbprint[] = {0xa1, 0x06, 0x6e, 0x13, 0xf2, 0x34, 0x49, 0x0a, 0x22, 0xd7, 0x6f, 0xb2, 0x80, 0xab, 0x68, 0x7d, 0x16, 0x55, 0xb3, 0x14};


  // Retrieve a pointer to the IBackgroundCopyJob4 interface.
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"QueryInterface for HttpOptions failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByID(BG_CERT_STORE_LOCATION_CURRENT_USER, 
      L"MY", Thumbprint);
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByID failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions)
  {
    hr = pHttpOptions->Release();
  }


要件

要件
サポートされている最小のクライアント Windows Vista
サポートされている最小のサーバー Windows Server 2008
対象プラットフォーム Windows
ヘッダー bits2_5.h (Bits.h を含む)
Library Bits.lib

こちらもご覧ください

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions::GetClientCertificate

IBackgroundCopyJobHttpOptions::RemoveClientCertificate

IBackgroundCopyJobHttpOptions::SetClientCertificateByName