ICertRequest：：Submit 方法 (certcli.h)

發行項
03/05/2024

Submit 方法會將要求提交至憑證服務伺服器。

如果產生的處置狀態CR_DISP_ISSUED，您可以呼叫 ICertRequest3：：GetCertificate 方法來擷取已簽發的憑證。

語法

HRESULT Submit(
  [in]          LONG       Flags,
  [in]          const BSTR strRequest,
  [in]          const BSTR strAttributes,
  [in]          const BSTR strConfig,
  [out, retval] LONG       *pDisposition
);

參數

[in] Flags

指定要求格式、要求類型，以及要求是否已加密。下列其中一個格式屬性旗標可用來指定要求編碼方式。

值	意義
CR_IN_BASE64	不含開始/結束的 Unicode BASE64 格式。
CR_IN_BASE64HEADER	開頭/結尾的 Unicode BASE64 格式。
CR_IN_BINARY	二進位格式。
CR_IN_ENCODEANY	請嘗試所有CR_IN_BASE64HEADER、CR_IN_BASE64或CR_IN_BINARY格式。

下列其中一個格式值旗標可用來指定要求的型別。

值	意義
CR_IN_RETURNCHALLENGE	傳回可以提交至 CA 的挑戰。挑戰是 CMS 的憑證管理 (CMC) 完整要求。開啟此旗標時，使用 FR_PROP_FULLRESPONSE 旗標呼叫 GetFullResponseProperty 方法會傳回包含密鑰證明挑戰的 CMC 回應。
CR_IN_CHALLENGERESPONSE	呼叫是挑戰的回應。 RequestId 必須在 strAttributes 參數中傳遞，而且必須傳遞對挑戰的回應，才能在 strRequest 參數中傳遞。當應用程式需要將解密的挑戰傳回給 CA 時，應該開啟此旗標。然後，您可以呼叫 GetFullResponseProperty 方法來取得發行的結束實體憑證。
CR_IN_CMC	CMS (CMC 的憑證管理) 要求。
CR_IN_FORMATANY	請嘗試所有CR_IN_CMC、CR_IN_KEYGEN、CR_IN_PKCS7或CR_IN_PKCS10格式。
CR_IN_KEYGEN	Keygen 要求 (Netscape 格式) 。
CR_IN_PKCS7	PKCS #7 要求 (續約或註冊代理程式) 。
CR_IN_PKCS10	PKCS #10 要求。
CR_IN_RPC	使用 RPC 而非 DCOM 傳輸訊息。
CR_IN_FULLRESPONSE	傳回完整的 CMC 回應。
CR_IN_CRLS	包含目前的證書吊銷清單。
CR_IN_MACHINE	使用金鑰服務計算機的內容。
CR_IN_ROBO	表示正在代表另一個發件者要求訊息。如果證書頒發機構單位 (CA) 未設定為「代表更新」，則 CA 會拒絕要求。如需在 CA 上啟用「代表更新」的詳細資訊，請參閱設定憑證註冊 Web 服務以僅更新模式。要求必須是更新要求，且簽署憑證必須與要求使用相同的範本。此外，只有在下列其中一個條件成立時，要求才會成功：簽署憑證必須由相同的 CA 發行簽署憑證的SAN2延伸模組具有主體的UPN 簽署憑證的主體名稱具有主體FQDN_1779 Windows Server 2008 和 Windows Server 2003：不支援此旗標。
CR_IN_CLIENTIDNONE	請勿包含在識別用戶端的要求數據中。 Windows Server 2008 和 Windows Server 2003：不支援此旗標。
CR_IN_CONNECTONLY	指定建立與伺服器的 DCOM 連線，但不會提交要求。

[in] strRequest

包含憑證要求的字串指標。如果在 Flags 中指定CR_IN_BASE64或 CR_IN_BASE64HEADER，strRequest 必須是 Unicode 字串。

[in] strAttributes

字串的指標，其中包含要求的選擇性額外屬性。每個屬性都是名稱/值字串組。冒號字元會分隔名稱和值，而換行符元會分隔多個名稱/值組，例如：

C++	“AttributeName1：AttributeValue1\nAttributeName2：AttributeValue2”
VB	“AttributeName1：AttributeValue1” & vbNewLine & “AttributeName2：AttributeValue2”

當憑證服務伺服器剖析屬性名稱時，它會忽略空格、連字元 (減號) 和大小寫。例如，“AttributeName1”、“Attribute Name1” 和 “Attribute-name1” 全都相等。針對屬性值，憑證服務伺服器會忽略開頭和尾端空格符。

[in] strConfig

表示憑證服務伺服器的有效組態字串。此字串可以是註冊伺服器的 HTTPS URL，或是 以 ComputerName\CAName 格式表示，其中 ComputerName 是伺服器的網路名稱， 而 CAName 是證書頒發機構單位的一般名稱，如憑證服務設定期間輸入。如需組態字串名稱的相關信息，請參閱 ICertConfig。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支援 HTTPS URL 作為輸入。

[out, retval] pDisposition

要求處置值的指標。

傳回值

C++

如果方法成功，方法會傳回S_OK。

成功完成此函式時，*pDisposition 會設定為下表中的其中一個值。

如果方法失敗，它會傳回 HRESULT 值，指出錯誤。如需常見錯誤碼的清單，請參閱一般 HRESULT 值。

VB

傳回值會指定要求的處置。處置是下列其中一個值。

傳回碼	Description
CR_DISP_DENIED	要求遭拒
CR_DISP_ERROR	要求失敗
CR_DISP_INCOMPLETE	要求未完成
CR_DISP_ISSUED	已發出憑證
CR_DISP_ISSUED_OUT_OF_BAND	個別發行的憑證
CR_DISP_UNDER_SUBMISSION	提交下所採取的要求

備註

如果您從檔案讀取 BASE64 格式要求，請確定檔案位於 Unicode 中，或在使用此方法提交要求之前從 ASCII 轉換為 Unicode。

範例

    //  The pointer to the interface object.
    ICertRequest * pCertRequest = NULL;

    //  The variable for the computer\CAName.
    BSTR         bstrCA = NULL;

    //  The variable for the request.
    BSTR         bstrRequest = NULL;

    //  The variable for the attributes.
    BSTR         bstrAttribs = NULL;

    //  The variable for the disposition code.
    long        nDisp;

    HRESULT     hr;

    //  Initialize COM.
    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    //  Check status.
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx [%x]\n", hr);
        goto error;
    }

    //  Instantiate the CertConfig object.
    hr = CoCreateInstance(CLSID_CCertRequest,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_ICertRequest,
                          (void **)&pCertRequest);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance pCertRequest [%x]\n", hr);
        goto error;
    }

    //  Specify the certification authority.
    //  Note: In C++, produce one backslash (\) by using two.
    bstrCA = SysAllocString(L"server01\\myCAName");

    //  Create the request (not shown), and assign it to bstrRequest,
    //  for example, use ICEnroll::createPKCS10.

    //  Generate the attributes. In this case, no attributes
    //  are specified.
    bstrAttribs = SysAllocString(L"");
    
    //  Submit the request.
    hr = pCertRequest->Submit(CR_IN_BASE64 | CR_IN_PKCS10, 
                              bstrRequest,
                              bstrAttribs,
                              bstrCA, 
                              &nDisp );
    if (FAILED(hr))
    {
        printf("Failed Submit [%x]\n", hr);
        goto error;
    }
    else
    {
        //  Use the disposition value as needed.
    }

    //  Done processing.

error:

    //  Free BSTR values.
    if (NULL != bstrCA)
        SysFreeString(bstrCA);

    if (NULL != bstrRequest)
        SysFreeString(bstrRequest);

    if (NULL != bstrAttribs)
        SysFreeString(bstrAttribs);

    //  Clean up object resources.
    if (NULL != pCertRequest)
        pCertRequest->Release();

    //  Free COM resources.
    CoUninitialize();

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	certcli.h (包含 Certsrv.h)
程式庫	Certidl.lib
Dll	Certcli.dll