3.1.4.2.2 ICertAdminD2::GetCAProperty (Opnum 32)

  • Article

The GetCAProperty method is used to retrieve the value of a specific property from the CA. 

 HRESULT GetCAProperty(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in] LONG PropId,
   [in] LONG PropIndex,
   [in] LONG PropType,
   [out, ref] CERTTRANSBLOB* pctbPropertyValue
 );

pwszAuthority:  See the pwszAuthority definition in section 3.1.4.1.1.

PropId: An integer value specifying the property to be returned. The PropID value MUST be one of the values in the table labeled PropId in [MS-WCCE] section 3.2.1.4.3.2. If a value other than one of the listed values is used, the error E_INVALIDARG is returned.

PropIndex: Some of these properties (the ones labeled "indexed" in the table in [MS-WCCE] section 3.2.1.4.3.2) have arrays of values. This parameter MUST be used as the index into such an array. For properties that are not arrays, this parameter MUST be ignored.

PropType: An integer value that specifies the property data type.

Value

Meaning

PROPTYPE_LONG

0x00000001

The property type is a signed long integer or a byte array.

PROPTYPE_BINARY

0x00000003

The property type is binary data.

PROPTYPE_STRING

0x00000004

The property type is a Unicode string.

pctbPropertyValue:  If the function succeeds, this method MUST return a CERTTRANSBLOB structure that contains the property value. If the function fails, the contents are undefined.

Note The numeric values for the constants listed in this topic are defined in the table for the PropID parameter.

The data type of the value returned depends on the value specified in the PropType parameter and the property specified in the PropID parameter:

  • If PROPTYPE_STRING is specified in the PropType parameter, pctbPropertyValue MUST be a pointer to a CERTTRANSBLOB structure. The pb member of the structure points to the little-endian encoded Unicode string. The length, in bytes, of the string MUST be contained in the cb member.

  • If PROPTYPE_LONG is specified in the PropType parameter, there are two possible return types depending on the PropID. The first type is the return of a CAINFO structure (as specified in [MS-WCCE] section 2.2.2.4) and the second type is for the return of a BYTE array:

    • If the value passed in PropId maps to one of the following properties, pctbPropertyValue is a pointer to a CERTTRANSBLOB structure, and the pb member of that structure MUST contain a pointer to a CAINFO structure that contains the values of the properties listed as follows. The marshaling rules for a CAINFO structure in a CERTTRANSBLOB are specified in [MS-WCCE] section 2.2.2.2.5:

      • CR_PROP_CATYPE

      • CR_PROP_CASIGCERTCOUNT

      • CR_PROP_CAXCHGCERTCOUNT

      • CR_PROP_EXITCOUNT

      • CR_PROP_CAPROPIDMAX

      • CR_PROP_KRACERTUSEDCOUNT

      • CR_PROP_ROLESEPARATIONENABLED

      • CR_PROP_KRACERTCOUNT

      • CR_PROP_ADVANCEDSERVER

    • If the value passed in PropId maps to one of the following properties, pctbPropertyValue is a pointer to a CERTTRANSBLOB structure, and the pb member of the structure points to a byte array containing the value for the requested property. The marshaling rules for each property are specified in the subsection of [MS-WCCE] section 3.2.1.4.3.2 that corresponds to the property name. The cb member contains the length of the byte array:

      • CR_PROP_CACERTSTATE

      • CR_PROP_CRLSTATE

      • CR_PROP_KRACERTSTATE

      • CR_PROP_BASECRLPUBLISHSTATE

      • CR_PROP_DELTACRLPUBLISHSTATE

      • CR_PROP_CACERTSTATUSCODE

      • CR_PROP_CAFORWARDCROSSCERTSTATE

      • CR_PROP_CABACKWARDCROSSCERTSTATE

  • If PROPTYPE_BINARY is specified in the PropType parameter, pctbPropertyValue MUST be a pointer to a CERTTRANSBLOB structure. The pb member of the structure points to the requested binary large object (BLOB).

    Based on the property identifier passed in PropId, the binary data pointed to by the pb member MUST be populated as follows:

    • CR_PROP_CASIGCERT: MUST be an X.509 certificate encoded using DER, as specified in [X660].

    • CR_PROP_BASECRL: MUST be a X.509 CRL encoded using DER, as specified in [X660].

    • CR_PROP_CAFORWARDCROSSCERT: MUST be a X.509 certificate encoded using DER, as specified in [X660].

    • CR_PROP_CABACKWARDCROSSCERT: MUST be a X.509 certificate encoded using DER, as specified in [X660].

    • CR_PROP_CAXCHGCERT: MUST be a X.509 certificate encoded using DER, as specified in [X660].

    The CA MUST execute the processing rules specified in [MS-WCCE] section 3.2.1.4.3.2.15, "PropID = 0x0000000F (CR_PROP_CAXCHGCERT) "CA Exchange Certificate"".

    • CR_PROP_CAXCHGCERTCHAIN: MUST be a CMS message, as specified in [RFC2797]encoded using DER, as specified in [X660].

    The CA MUST execute the processing rules specified in [MS-WCCE] section 3.2.1.4.3.2.16, "PropID = 0x00000010 (CR_PROP_CAXCHGCERTCHAIN) "CA Exchange Certificate Chain"".

    • CR_PROP_CASIGCERTCHAIN: MUST be a CMS message [RFC2797] encoded using DER. [X660].

    • CR_PROP_CASIGCERTCRLCHAIN: MUST be a CMS message, as specified in [RFC2797], encoded using DER, as specified in [X660].

    • CR_PROP_CASIGCERTCRLCHAIN: MUST be a CMS message, as specified in [RFC2797], encoded using DER, as specified in [X660].

    • CR_PROP_CAXCHGCERTCRLCHAIN: CR_PROP_CASIGCERTCRLCHAIN: MUST be a CMS message, as specified in [RFC2797], encoded using DER, as specified in [X660].

    The CA MUST execute the processing rules specified in [MS-WCCE] section 3.2.1.4.3.2.33, "PropID = 0x00000021 (CR_PROP_CAXCHGCERTCRLCHAIN) "CA Exchange Certificate Chain and CRL"".

    • CR_PROP_DELTACRL: MUST be a X.509 CRL encoded using DER [X660].

    • CR_PROP_KRACERT: MUST be a X.509 CRL encoded using DER, as specified in [X660].

The marshaling rules for each of the preceding properties into a CERTTRANSBLOB are specified in [MS-WCCE] sections 2.2.2.2.2 (for X.509 certificate), 2.2.2.2.3 (X.509 CRL), and 2.2.2.2.4 (CMS message).