184.108.40.206.2.2 ICertRequestD::GetCACert (Opnum 4)
The GetCACert method returns property values on the CA. The main use of this method is to enable clients to diagnose issues and the state of the server. In addition, one of the properties returned by this method is required to support the advanced CA functionality (GETCERT_CAXCHGCERT).
HRESULT GetCACert( [in] DWORD fchain, [in, string, unique, range(1, 1536)] wchar_t const * pwszAuthority, [out, ref] CERTTRANSBLOB* pctbOut );
fchain: Specifies the type of information to include in the output parameter.
pwszAuthority: Contains the name of the CA.
pctbOut: If the function returns success (0) this parameter is a pointer to a CERTTRANSBLOB structure containing the returned value.
Return Values: For successful invocation, the CA MUST return 0; otherwise, the CA MUST return a nonzero value.
The processing rules for this method are as follows.
If the server implements the advanced CA functionality, it MUST implement the GETCERT_CAXCHGCERT property specified as follows.
If Config_CA_Interface_Flags contains the value IF_NOREMOTEICERTREQUEST, the server SHOULD return 0x80094011 (CERTSRV_E_ENROLL_DENIED) to the client.<76>
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 220.127.116.11.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.
The fchain parameter MUST be one of the values in the first table that follows, or the two most significant bytes of fchain MUST be one of the values in the second table that follows.
The request is for a CA signing certificate.
The request is for a CA exchange certificate.
The request is for a string value containing the version number of the CA implementation.
The request is for a specific CA informational block, marshaled as a CAINFO structure.
The request is for the name of the parent CA to the current CA.
The request is for the policy algorithm description.
The request is for a string value that contains the product version (build number) of the CA.
The request is for a common shared folder location. The shared folder is a UNC path name. This property was implemented for CAs deployed in a network without Active Directory. For more information on Windows implementation and usage for shared folders, see [MSFT-SHAREDFOLDER].
The request is for the CA type.
The values in the following table define the indexed properties for the fchain parameter. The two most significant bytes of fchain define the property type, and the two least significant bytes of fchain define the index required for these properties.
For example, a property with the value 0x636C0002 is the GETCERT_CRLBYINDEX value with the index value of 0x0002.
The request is for the CRL at the specified index. The index of the CRL MUST represent the CA certificate that is associated with the CRL. Because each CRL has an index, this method provides the means to retrieve a specific CRL based on its index. The CA Abstract Data Model is specified in section 18.104.22.168.
The request is for the CA certificate at the specified index. The index MUST refer to the number of the certificate of the CA. Because each CA certificate has an index, this method provides the means to retrieve a specific certificate based on its index.
The request is for the exit algorithm description at the specified index.
The request is for the CRL state at the specified index.
The request is for the CA certificate state at the specified index.
If the value is not one of the preceding specified values, the server MUST return an error, which SHOULD be 0x80070057.
If fchain doesn't equal GETCERT_SANITIZEDCANAME (0x73616E69) or GETCERT_CANAME (0x6E616D65), the server MUST invoke the processing rules in section 22.214.171.124.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.
Returned data type:
The data type of the value returned depends on the value specified in the fchain parameter:
A [UNICODE] null-terminated string: A [UNICODE] string MUST be returned if fchain is equal to one of the following values:
Marshaling rules for [UNICODE] strings MUST be as specified in section 126.96.36.199.1.
A CAINFO structure: A CAINFO structure MUST be returned if fchain is equal to the following:
Marshaling rules for CAINFO MUST be as specified in section 188.8.131.52.5.
A CRL: A CRL MUST be returned if fchain is equal to the following:
Marshaling rules for a CRL MUST be as specified in section 184.108.40.206.3.
[X509] Certificate: A certificate MUST be returned if fchain is equal to the following:
Marshaling rules for [X509] certificates MUST be as specified in section 220.127.116.11.2.
Byte array: A byte array MUST be returned if fchain is equal to the following:
Marshaling: pctbOut MUST be a pointer to a CERTTRANSBLOB structure. The pb member of the structure MUST point to the byte array.
An unsigned integer: An unsigned integer MUST be returned if fchain is equal to the following:
Marshaling: pctbOut MUST be a pointer to a CERTTRANSBLOB structure. The pb member of the structure MUST point to an unsigned integer in little-endian format.
Note The numeric values for these constants are defined in the preceding table.
Computing the returned values: