3.2.1.4.2.1 ICertRequestD::Request (Opnum 3)

  • Article

The Request method initiates the certificate issuance process.

 HRESULT Request(
   [in] DWORD dwFlags,
   [in, string, unique, range(1, 1536)] wchar_t const * pwszAuthority,
   [in, out, ref] DWORD* pdwRequestId,
   [out] DWORD* pdwDisposition,
   [in, string, unique, range(1, 1536)] wchar_t const * pwszAttributes,
   [in, ref] CERTTRANSBLOB const * pctbRequest,
   [out, ref] CERTTRANSBLOB* pctbCertChain,
   [out, ref] CERTTRANSBLOB* pctbEncodedCert,
   [out, ref] CERTTRANSBLOB* pctbDispositionMessage
 );

dwFlags: This field MUST contain packed data as specified in section 3.2.1.4.3.1.1. The data in this field MUST define the structure of the pctbRequest parameter and the expected content in pctbCertChain.

pwszAuthority: A null-terminated [UNICODE] string that contains the name of the CA.

pdwRequestId: A 32-bit integer value that contains the identifier used to identify the request. Details about processing information are specified in section 3.1.1.4.3.

pdwDisposition: An unsigned integer that identifies the request status for this invocation. The value MUST be one of the following:

  • CR_DISP_ISSUED, 0x00000003: The requested certificate was issued.

  • CR_DISP_UNDER_SUBMISSION, 0x00000005: The requested certificate was not issued and is now in a pending state waiting for additional processing before it can be issued.

  • A nonzero value, excluding 0x00000003 and 0x00000005, indicating an error.

pwszAttributes: A null-terminated [UNICODE] string that contains a set of request attributes. The parameter contains zero or more request attributes, which MUST be empty or take the form of name/value pairs. The name/value pairs MUST be formatted as "Name:Value". A colon MUST be the separator, and a new line ('\n') MUST separate name/value pairs.

pctbRequest: A CERTTRANSBLOB structure that contains a certificate request as a raw binary object. This request binary object can be in one of a number of formats. The format used is specified in the dwFlags parameter. The syntax of that structure is provided in section 2.2.2.8.

pctbCertChain: A CERTTRANSBLOB structure that is empty or contains a simple CMS or a CMC full PKI response for the certificate chain issued by the CA based on the request (in the pctbRequest parameter) supplied by the caller. The parameter format is as requested by the client in the dwFlags parameter. Message syntax MUST be as specified in section 2.2.2.2.

pctbEncodedCert: A CERTTRANSBLOB structure that is empty or contains the issued certificate. The returned value MUST be an X509 cert encoded by using DER, as specified in [X660]. Message syntax MUST be as specified in section 2.2.2.2.

pctbDispositionMessage:  A CERTTRANSBLOB structure that contains a null-terminated [UNICODE] string with a message that identifies the status of the request. Message syntax MUST be as specified in section 2.2.2.2.

Return Values:  The method MUST return zero unless otherwise explicitly stated in this section. The server MUST return errors through the pdwDisposition parameter.

This section, and the following sections, describe the processing rules for ICertRequestD::Request and ICertRequestD2::Request2.

The following is an overview of the CA processing rules for these methods:

The CA MUST obtain the end entity account name and SID by performing the processing rules in section 3.2.1.4.1.2 and storing the returned Output_Account_Name in the Per_Request.Caller_Account_Name ADM element and the returned Output_SID in Per_Request.Caller_SID.

If Config_CA_Interface_Flags contains the value IF_NOREMOTEICERTREQUEST, the server SHOULD return 0x80094011 (CERTSRV_E_ENROLL_DENIED) to the client.<69>

If Config_CA_Interface_Flags contains the value IF_ENFORCEENCRYPTICERTREQUEST and the RPC_C_AUTHN_LEVEL_PKT_PRIVACY authentication level, as defined in [MS-RPCE] section 2.2.1.1.8, is not specified on the RPC connection from the client, the CA MUST refuse to establish a connection with the client by returning a nonzero error.<70>

  1. The CA MUST verify the CA name passed in the pwszAuthority attribute by invoking the processing rules in section 3.2.1.4.2.1.1 with the CANameString input parameter set to the CA name passed in the pwszAuthority parameter and the EmptyNameAllowed input parameter set to false. If false is returned, the CA MUST return the E_INVALIDARG (0x80070057) error code to the client.

  2. The CA MUST parse attributes passed in pwszAttributes parameter as specified in section 3.2.1.4.2.1.2.

  3. The CA MUST check if the request is a status inspection as specified in section 3.2.1.4.2.1.3 and process it accordingly if it is. If it is not, it is a new or renewal request and the CA MUST proceed to the following steps.

  4. If the value of the pdwRequestId parameter is 0, the CA MUST process the request BLOB as specified in section 3.2.1.4.2.1.4.

  5. The CA MUST store the request fields in the Request table as specified in sections 3.2.1.4.2.1.4.4 and 3.2.1.4.2.1.4.5.

  6. The CA MUST call its CA policy algorithm implementation as specified in section 3.2.1.4.2.1.4.5.

  7. If the CA policy algorithm implementation decided to issue a certificate, then the CA MUST sign the certificate as specified in section 3.2.1.4.2.1.3.

  8. If the CA policy algorithm implementation decided to issue a certificate, then the CA MUST follow the post processing rules as specified in section 3.2.1.4.2.1.4 and construct the certificate as specified in section 3.2.1.4.2.1.4.7.

  9. The CA MUST set the following values for the out parameters:

    • pdwDisposition: If a certificate was issued, then the CA MUST return 0x00000003; if a certificate issuance requires manager approval, then the CA MUST return 0x00000005. If an error was encountered, the CA MUST set the value of this parameter to a non-zero value.

    • pctbCertChain: If a certificate was issued, then the CA MUST return the issued certificate and its full chain as constructed in section 3.2.1.4.2.1.4.8 in this parameter.

    • pctbEncodedCert: If a certificate was issued, then the CA MUST return the issued certificate in this parameter.

    • pctbDispositionMessage: In this parameter, the CA SHOULD send additional information in the form of a Unicode string that can be used to troubleshoot the server response.<71>