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

[アーティクル]
03/14/2023

HTTPS (SSL) 要求でのクライアント認証に使用するクライアント証明書のサブジェクト名を指定します。

構文

HRESULT SetClientCertificateByName(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] LPCWSTR                SubjectName
);

パラメーター

[in] StoreLocation

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

[in] StoreName

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

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

[in] SubjectName

証明書の単純なサブジェクト名を含む Null で終わる文字列。サブジェクト名に複数の相対識別名 (RDN) が含まれている場合は、隣接する 1 つ以上の RDN を指定できます。複数の RDN を指定した場合、リストはコンマ区切りになります。文字列は、null ターミネータを含め、256 文字に制限されています。空のサブジェクト名を指定することはできません。

名前にオブジェクト識別子を含めないでください。証明書の表示とは逆の順序で RDN を指定する必要があります。たとえば、証明書のサブジェクト名が "CN=name1,OU=name2, O=name3" の場合は、サブジェクト名を "name3, name2, name1" と指定します。

戻り値

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

リターンコード	説明
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 パラメーターまたは SubjectName パラメーターを NULL にすることはできません。
BG_E_STRING_TOO_LONG	StoreName または SubjectName パラメーターは 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 つの一致を見つける可能性を高めるには、完全なサブジェクト名を指定する必要があります。証明書が正しくない (信頼されていない) 場合、BITS がファイルの転送を試み、ジョブがエラー状態に移行すると、ジョブは BG_E_HTTP_ERROR_403 で失敗します。一意のサブジェクト名を保証できない場合は、代わりに IBackgroundCopyJobHttpOptions::SetClientCertificateByID メソッドの使用を検討してください。

SmartCard 証明書識別子 (拇印) はサポートされていません。

例

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


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;

  // Change list of names to actual list of names.
  LPWSTR pSubjectName = L"name3, name2, name1";  
                                                    
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByName(BG_CERT_STORE_LOCATION_CURRENT_USER, 
                                      L"MY", pSubjectName));
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByName 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