ICertRequest：：Submit 方法 (certcli.h)

项目
02/28/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	(Netscape 格式) 的 Keygen 请求。
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 服务。请求必须是续订请求，签名证书必须使用与请求相同的模板。此外，仅当以下条件之一为 true 时，请求才会成功：签名证书必须由同一 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

返回值指定请求的处置。处置是以下值之一。

返回代码	说明
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)
Library	Certidl.lib
DLL	Certcli.dll