3.2.1.4.3.2 ICertRequestD2::GetCAProperty (Opnum 7)

The GetCAProperty method retrieves a property value from the CA.

 HRESULT GetCAProperty(
   [in, string, unique, range(1, 1536)] wchar_t const * pwszAuthority,
   [in] long PropID,
   [in] long PropIndex,
   [in] long PropType,
   [out, ref] CERTTRANSBLOB* pctbPropertyValue
 );

pwszAuthority: Contains the name of the CA.

PropID:  An integer value that specifies the property to be returned.

Property name

Numerical value

Type/Index

Meaning

CR_PROP_FILEVERSION

0x00000001

String

A string that MUST contain the CA version information.

CR_PROP_PRODUCTVERSION

0x00000002

String

A string that MUST contain the build number of the CA.

CR_PROP_EXITCOUNT

0x00000003

Long

MUST be the number of exit algorithms registered on the CA.

CR_PROP_EXITDESCRIPTION

0x00000004

String

indexed

A string that MUST contain the name of the exit algorithm identified by the PropIndex parameter.

CR_PROP_POLICYDESCRIPTION

0x00000005

String

A string that MUST contain the description of the policy algorithm on the CA.

CR_PROP_CANAME

0x00000006

String

A string that MUST contain the CN, as specified in [RFC3280], of a CA.

CR_PROP_SANITIZEDCANAME

0x00000007

String

A string that MUST contain the sanitized name of the CA. More information about sanitized name is specified in section 3.1.1.4.1.1.

CR_PROP_SHAREDFOLDER

0x00000008

String

A string that MUST contain the UNC path of a folder that contains the CA information and signature certificates.

CR_PROP_PARENTCA

0x00000009

String

A string that MUST contain the name of the parent CA to the current CA.

CR_PROP_CATYPE

0x0000000A

Long

MUST be a CAINFO structure that MUST contain the CA type. More information is specified in section 3.2.1.4.3.2.10.

CR_PROP_CASIGCERTCOUNT

0x0000000B

Long

MUST be the number of signing certificates on the CA.

CR_PROP_CASIGCERT

0x0000000C

Binary, indexed

MUST be a binary object that contains a signing certificate identified by the PropIndex parameter.

CR_PROP_CASIGCERTCHAIN

0x0000000D

Binary, indexed

MUST be a binary object that contains the certificate chain for a signing certificate identified by the PropIndex parameter.

CR_PROP_CAXCHGCERTCOUNT

0x0000000E

Long

MUST be 0x1.

CR_PROP_CAXCHGCERT

0x0000000F

Binary, indexed

MUST be a binary object that contains the CA's current exchange certificate from the Current_CA_Exchange_Cert datum. The PropIndex parameter MUST be 0x0 or 0xFFFFFFFF.

CR_PROP_CAXCHGCERTCHAIN

0x00000010

Binary, indexed

MUST be a binary object that contains the certificate chain for the CA's current exchange certificate from the Current_CA_Exchange_Cert datum. The PropIndex parameter MUST be 0x0 or 0xFFFFFFFF.

CR_PROP_BASECRL

0x00000011

Binary, indexed

MUST be a CRL, for a CA signing certificate identified by the PropIndex parameter.

CR_PROP_DELTACRL

0x00000012

Binary, indexed

MUST be a delta CRL, for a CA signing certificate identified by the PropIndex parameter. For more information about delta CRLs, see [MSFT-CRL]. Additional information is specified in [RFC3280] section 5.2.

CR_PROP_CACERTSTATE

0x00000013

Long

indexed

MUST be a byte array that contains the disposition status of all CA signing certificates. Disposition status is specified in section 3.2.1.4.3.2.19.

CR_PROP_CRLSTATE

0x00000014

Long

indexed

MUST be a byte array that contains the status for all the CRLs of the CA.

CR_PROP_CAPROPIDMAX

0x00000015

Long

MUST be the maximum property identifier supported by the CA.

CR_PROP_DNSNAME

0x00000016

String

MUST be the fully qualified domain name (FQDN) of the computer on which the CA is installed.

CR_PROP_ROLESEPARATIONENABLED

0x00000017

Long

Indicates whether administrative role separation has been enabled on the CA. A nonzero return value means that role separation has been enabled. Zero means that role separation has not been enabled.

CR_PROP_KRACERTUSEDCOUNT

0x00000018

Long

MUST be the minimum number of KRAs to use when archiving a private key. For more information about KRA usage, see [MSFT-ARCHIVE].

CR_PROP_KRACERTCOUNT

0x00000019

Long

MUST be the maximum number of KRA certificates available on the CA.

CR_PROP_KRACERT

0x0000001A

Binary, indexed

A KRA certificate identified by the PropIndex parameter.

CR_PROP_KRACERTSTATE

0x0000001B

Long, indexed

MUST be a byte array that contains the status of the KRA certificates registered with the CA.

CR_PROP_ADVANCEDSERVER

0x0000001C

Long

MUST identify whether the CA operating system is an advanced server platform.

CR_PROP_TEMPLATES

0x0000001D

String

MUST be a collection of name and OID pairs that identify the templates supported by a CA.

CR_PROP_BASECRLPUBLISHSTATUS

0x0000001E

Long, indexed

MUST be the publishing status of a signing certificate base CRL identified by the PropIndex parameter.

CR_PROP_DELTACRLPUBLISHSTATUS

0x0000001F

Long, indexed

MUST be the publishing status of a signing certificate delta CRL identified by the PropIndex parameter.

CR_PROP_CASIGCERTCRLCHAIN

0x00000020

Binary, indexed

MUST be a binary object that contains the certificate chain for a signing certificate and the CRL for the certificates in the chain identified by the PropIndex parameter.

CR_PROP_CAXCHGCERTCRLCHAIN

0x00000021

Binary, indexed

MUST be a binary object for a chain containing CRLs for the CA's current exchange certificate from the Current_CA_Exchange_Cert datum. The PropIndex parameter MUST be 0x00000000 or 0xFFFFFFFF.

CR_PROP_CACERTSTATUSCODE

0x00000022

Long, indexed

MUST be an HRESULT that identifies the result of certificate validation, as specified in [RFC3280], by the CA for the CA signing certificates identified by the PropIndex parameter.

CR_PROP_CAFORWARDCROSSCERT

0x00000023

Binary, indexed

MUST be a forward cross certificate, by index, from a CA. For more information about cross certificates, see [MSFT-CROSSCERT].

CR_PROP_CABACKWARDCROSSCERT

0x00000024

Binary, indexed

MUST be a backward cross certificate, by index, from a CA. For more information about cross certificates, see [MSFT-CROSSCERT].

CR_PROP_CAFORWARDCROSSCERTSTATE

0x00000025

Long, indexed

MUST be a byte array that identifies the status of all backward cross certificates for a CA.

CR_PROP_CABACKWARDCROSSCERTSTATE

0x00000026

Long, indexed

MUST be a byte array that identifies the disposition status of all forward cross certificates for a CA.

CR_PROP_CACERTVERSION

0x00000027

Long, indexed

MUST be an indexed 32-bit integer that contains the version number of a CA signing certificate.

CR_PROP_SANITIZEDCASHORTNAME

0x00000028

String

The property MUST return the sanitized shortened name of the CA. More information about the sanitized name is specified in section 3.1.1.4.1.1.

CR_PROP_CERTCDPURLS

0x00000029

String, indexed

MUST be a null-terminated [UNICODE] string of the format "String1\nString2\n", where each string (separated by '\n') MUST represent a URI to be part of a CRL Distribution Point (CDP) extension, as specified in [RFC3280] section 4.2.1.14.

CR_PROP_CERTAIAURLS

0x0000002A

String, indexed

MUST be a null-terminated [UNICODE] string of the format "String1\nString2\n", where each string (separated by '\n') MUST represent a URI to be part of Authority Information Access extension, as specified in [RFC3280] section 4.2.2.1.

CR_PROP_CERTAIAOCSPRLS

0x0000002B

String, indexed

MUST be a null-terminated [UNICODE] string of the format "String1\nString2\n", where each string (separated by '\n') MUST represent the OCSP URLs configured on the CA, as specified in [RFC3280] section 4.2.2.1.

CR_PROP_LOCALENAME

0x0000002C

String

MUST be a null-terminated [UNICODE] string in the 'Language-Region' format (as specified in [RFC4646]) that represents the locale of the CA.

CR_PROP_SUBJECTTEMPLATE_OIDS

0x0000002D

String

MUST be a null-terminated [UNICODE] string of the format "OID1\nOID2\n", where each OID (separated by '\n') MUST represent a Relative Distinguished Name that is in a certificate Subject Distinguished Name.

PropIndex: This parameter is used as the index to a property that can contain multiple values.

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

pctbPropertyValue: If the function succeeds, this method returns a CERTTRANSBLOB structure in this parameter that contains the property value. If the function fails, the content of this parameter is undefined.

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

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 Config_CA_Interface_Flags contains the value IF_NOREMOTEICERTREQUEST, the server SHOULD return 0x80094011 (CERTSRV_E_ENROLL_DENIED) to the client.<80>

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 non-zero error.

If the server implements advanced CA functionality, it MUST implement the CR_PROP_CAXCHGCERT property that is specified in section 3.2.1.4.3.2.15.

To return server properties to the client using this method, the server implementation MUST follow the processing rules specified as follows.

  1. Validate arguments: 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.

  2.  Returned server property: The server MUST follow the steps that are specified in section 3.2.1.4.3.2.2.

The following table defines the values that MUST be set for the PropIndex and PropType parameters for each property value passed via the PropID parameter.

PropID value

PropIndex MUST be

PropType MUST be

0x01

0x00000000

0x00000004

0x02

0x00000000

0x00000004

0x03

0x00000000

0x00000001

0x04

The minimum index is 0. The maximum value is one less than the value stored in the Config_CA_Exit_Count datum.

0x00000004

0x05

0x00000000

0x00000004

0x06

0x00000000

0x00000004

0x07

0x00000000

0x00000004

0x08

0x00000000

0x00000004

0x09

0x00000000

0x00000004

0x0a

0x00000000

0x00000001

0x0b

0x00000000

0x00000001

0x0c

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000003

0x0d

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000003

0x0e

0x00000000

0x00000001

0x0f

0x00000000. An index of 0xFFFFFFFF is also valid and implies an index of 0x00000000.

0x00000003

0x10

0x00000000. An index of 0xFFFFFFFF is also valid and implies an index of 0x00000000.

0x00000003

0x11

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000003

0x12

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table.

0x00000003

0x13

ANY

0x00000001

0x14

ANY

0x00000001

0x15

0x00000000

0x00000001

0x16

0x00000000

0x00000004

0x17

0x00000000

0x00000001

0x18

0x00000000

0x00000001

0x19

0x00000000

0x00000001

0x1a

The minimum index is 0. The maximum index is one less than value of the Config_CA_KRA_Cert_Count datum.

0x00000003

0x1b

ANY

0x00000001

0x1c

0x00000000

0x00000001

0x1d

0x00000000

0x00000004

0x1e

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000001

0x1f

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table.

0x00000001

0x20

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table.

0x00000003

0x21

0x00000000

0x00000003

0x22

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000001

0x23

The index corresponds to a particular CA signing certificate. Since the last CA signing certificate cannot have a forward cross certificate, the minimum index is 0 and the maximum index is two less than the count of rows in the Signing_Cert table.

0x00000003

0x24

The index corresponds to a particular CA signing certificate. Since the first CA signing certificate cannot have a backward cross certificate, the minimum index is 1 and the maximum index is one less than the count of rows in the Signing_Cert table.

0x00000003

0x25

ANY

0x00000001

0x26

ANY

0x00000001

0x27

ANY

0x00000001

0x28

0x00000000

0x00000004

0x29

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000004

0x2A

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table. An index of 0xFFFFFFFF is allowed and indicates the maximum valid index.

0x00000004

0x2B

The minimum index is 0. The maximum index is one less than the count of rows in the Signing_Cert table.

0x00000004

0x2C

0x00000000

0x00000004

When processing the GetCAProperty method, the server MUST determine its behavior based on the requested property ID (PropID parameter). All valid property IDs are listed in the preceding table.

The CA MUST return a nonzero error if either of the following conditions is met.

  • The value of PropID is not listed in the preceding table.

  • For a specific PropID value, the PropType value does not match the required values that are defined in the preceding table.

    For a specific non-indexed PropID value, the PropIndex value does not match the required values that are defined in the preceding table.

For a specific indexed PropID value, if the PropIndex value does not match the required values that are defined in the preceding table, the CA MUST return a nonzero error.

The following sections specify the CA behavior of the method for each requested property ID. The returned property MUST be returned to the caller in the pctbPropertyValue parameter as a CERTTRANSBLOB structure. The message format for this structure MUST be as specified in section 2.2.2.2 and its subsections.