3.2.1.4.2.2 ICertRequestD::GetCACert (Opnum 4)

  • Article

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 a 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.<81>

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.<82>

  1. 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.

    Value

    Meaning

    GETCERT_CASIGCERT 0x00000000

    The request is for a CA signing certificate.

    GETCERT_CAXCHGCERT 0x00000001

    The request is for a CA exchange certificate.

    GETCERT_CURRENTCRL 0x6363726C

    The request is for the current CRL in ASN.1 format encoded by using DER for the latest CA signing certificates.

    GETCERT_FILEVERSION 0x66696C65

    The request is for a string value containing the version number of the CA implementation.

    GETCERT_CAINFO 0x696E666F

    The request is for a specific CA informational block, marshaled as a CAINFO structure.

    GETCERT_CANAME 0x6E616D65

    The request is for the CA name. The CA name is a [UNICODE] string that contains the CN of the CA.

    GETCERT_PARENTCONFIG 0x70617265

    The request is for the name of the parent CA to the current CA.

    GETCERT_POLICYVERSION 0x706F6C69

    The request is for the policy algorithm description.

    GETCERT_PRODUCTVERSION 0x70726F64

    The request is for a string value that contains the product version (build number) of the CA.

    GETCERT_SANITIZEDCANAME 0x73616E69

    The request is for the CA sanitized name. The sanitized name algorithm is specified in section 3.1.1.4.1.1.

    GETCERT_SHAREDFOLDER 0x73686172

    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 implementation and usage for shared folders, see [MSFT-SHAREDFOLDER].

    GETCERT_CATYPE 0x74797065

    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.

    Value

    Meaning

    GETCERT_CRLBYINDEX 0x636C

    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 3.1.1.1.

    GETCERT_CACERTBYINDEX 0x6374

    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.

    GETCERT_EXITVERSIONBYINDEX 0x6578

    The request is for the exit algorithm description at the specified index.

    GETCERT_CRLSTATEBYINDEX 0x736C

    The request is for the CRL state at the specified index.

    GETCERT_CACERTSTATEBYINDEX 0x7374

    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.

  2. If fchain doesn't equal GETCERT_SANITIZEDCANAME (0x73616E69) or GETCERT_CANAME (0x6E616D65), the server MUST invoke 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.

  3. 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:

      • GETCERT_FILEVERSION

      • GETCERT_CANAME

      • GETCERT_PARENTCONFIG

      • GETCERT_POLICYVERSION

      • GETCERT_PRODUCTVERSION

      • GETCERT_SANITIZEDCANAME

      • GETCERT_SHAREDFOLDER

      • GETCERT_EXITVERSIONBYINDEX

        Marshaling rules for [UNICODE] strings MUST be as specified in section 2.2.2.2.1.

    • A CAINFO structure: A CAINFO structure MUST be returned if fchain is equal to the following:

      GETCERT_CAINFO

      Marshaling rules for CAINFO MUST be as specified in section 2.2.2.2.5.

    • A CRL: A CRL MUST be returned if fchain is equal to the following:

      GETCERT_CURRENTCRL

      GETCERT_CRLBYINDEX

      Marshaling rules for a CRL MUST be as specified in section 2.2.2.2.3.

    • [X509] Certificate: A certificate MUST be returned if fchain is equal to the following:

      GETCERT_CASIGCERT

      GETCERT_CAXCHGCERT

      GETCERT_CACERTBYINDEX

      Marshaling rules for [X509] certificates MUST be as specified in section 2.2.2.2.2.

    • Byte array: A byte array MUST be returned if fchain is equal to the following:

      GETCERT_CRLSTATEBYINDEX

      GETCERT_CACERTSTATEBYINDEX

      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:

      GETCERT_CATYPE

      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.

  4. Computing the returned values: