ICertRequest::Submit method (certcli.h)
The Submit method submits a request to the Certificate Services server.
If the resulting disposition status is CR_DISP_ISSUED, you can retrieve the issued certificate by calling the ICertRequest3::GetCertificate method.
Syntax
HRESULT Submit(
[in] LONG Flags,
[in] const BSTR strRequest,
[in] const BSTR strAttributes,
[in] const BSTR strConfig,
[out, retval] LONG *pDisposition
);
Parameters
[in] Flags
Specifies the request format, type of request, and whether the request is encrypted. One of the following format attribute flags can be used to specify how the request is encoded.
One of the following format value flags can be used to specify the type of the request.
| Value | Meaning |
|---|---|
|
Return a challenge that can be submitted to a CA. The challenge is a Certificate Management over CMS (CMC) full request. When this flag is turned on, calling the GetFullResponseProperty method with the FR_PROP_FULLRESPONSE flag returns a CMC response that contains key attestation challenge. |
|
The call is a response to a challenge. The RequestId must be passed in the strAttributes parameter and the response to the challenge must be passed in the strRequest parameter. This flag should be turned on when an application needs to send back the decrypted challenge to the CA. You can then call the GetFullResponseProperty method to get the issued end entity certificate. |
|
A Certificate Management over CMS (CMC) request. |
|
Try all of the CR_IN_CMC, CR_IN_KEYGEN, CR_IN_PKCS7, or CR_IN_PKCS10 formats. |
|
Keygen request (Netscape format). |
|
PKCS #7 request (renewal or registration agent). |
|
PKCS #10 request. |
|
Transmit the messages using RPC instead of DCOM. |
|
Return a full CMC response. |
|
Include the current certificate revocation lists. |
|
Use the context of the key service computer. |
|
Indicates that the message is being requested on behalf of another sender.
If the certification authority (CA) is not configured for "renew on behalf of", then the CA rejects the request. For more information about enabling "renew on behalf of" on the CA, see Configuring the Certificate Enrollment Web Service for Renewal Only Mode. The request must be a renewal request and the signing certificate must be using the same template as the request. In addition, the request will succeed only when one of the following conditions is true:
|
|
Do not include in the request data that identifies the client.
Windows Server 2008 and Windows Server 2003: This flag is not supported. |
|
Specifies that the DCOM connection with the server is established, but the request is not submitted. |
[in] strRequest
A pointer to the string that contains the certificate request. If CR_IN_BASE64 or CR_IN_BASE64HEADER was specified in Flags, strRequest must be a Unicode string.
[in] strAttributes
A pointer to the string that contains optional extra attributes for the request. Each attribute is a name-value string pair. The colon character separates the name and value, and a newline character separates multiple name-value pairs, for example:
| C++ | "AttributeName1:AttributeValue1\nAttributeName2:AttributeValue2" |
| VB | "AttributeName1:AttributeValue1" & vbNewLine & "AttributeName2:AttributeValue2" |
[in] strConfig
Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL for an enrollment server or in the form ComputerName\CAName, where ComputerName is the network name of the server, and CAName is the common name of the certification authority, as entered during Certificate Services setup. For information about the configuration string name, see ICertConfig.
Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: An HTTPS URL is not supported as an input.
[out, retval] pDisposition
A pointer to the request's disposition value.
Return value
C++
If the method succeeds, the method returns S_OK.Upon successful completion of this function, *pDisposition is set to one of the values in the following table.
If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.
VB
The return value specifies the disposition of the request. The disposition is one of the following values.| Return code | Description |
|---|---|
|
Request denied |
|
Request failed |
|
Request did not complete |
|
Certificate issued |
|
Certificate issued separately |
|
Request taken under submission |
Remarks
If you read a BASE64 format request from a file, ensure that the file is in Unicode, or convert it from ASCII to Unicode before submitting the request with this method.
Examples
// 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();
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | certcli.h (include Certsrv.h) |
| Library | Certidl.lib |
| DLL | Certcli.dll |