ICertAdmin2::GetCAProperty method

The GetCAProperty method retrieves a property value for the certification authority (CA). This method was first defined in the ICertAdmin interface.

Syntax


HRESULT GetCAProperty(
  [in]   const BSTR strConfig,
  [in]   LONG PropId,
  [in]   LONG PropIndex,
  [in]   LONG PropType,
  [in]   LONG Flags,
  [out]  VARIANT *pvarPropertyValue
);

Parameters

strConfig [in]

Represents a valid configuration string for the CA in the form COMPUTERNAME\CANAME, where COMPUTERNAME is the Certificate Services server's network name, and CANAME is the common name of the CA, as entered during Certificate Services setup. For information about the configuration string name, see ICertConfig.

Important  GetCAProperty does not clear the internal cache when the configuration string is changed. When you change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new configuration string.

PropId [in]

Specifies one of the following property identifiers.

ValueMeaning
CR_PROP_ADVANCEDSERVER

Data type of the property: Long

Specifies whether the CA is running Advanced Server.

CR_PROP_BASECRL

Data type of the property: Binary, indexed

The CA's full, or base, certificate revocation list (CRL).

CR_PROP_BASECRLPUBLISHSTATUS

Data type of the property: Long, indexed

The base CRL publish status. For more details, see Remarks.

CR_PROP_CABACKWARDCROSSCERT

Data type of the property: Binary, indexed

The backward cross certificate. A backward cross certificate is the certificate issued upon renewal from the CA to itself signed with CA's new key. The backward cross certificate has the authority key identifier of the new CA certificate and the subject key identifier of the old CA certificate.

Applies to root CAs only.

CR_PROP_CABACKWARDCROSSCERTSTATE

Data type of the property: Long, indexed

Whether the backward cross certificate is valid. Valid for root CAs only.

CR_PROP_CACERTSTATE

Data type of the property: Long

State of the CA certificate. The values can be:

  • CA_DISP_REVOKED
  • CA_DISP_VALID
  • CA_DISP_INVALID
CR_PROP_CACERTSTATUSCODE

Data type of the property: Long, indexed

Status of the CA certificate, as an HRESULT.

CR_PROP_CACERTVERSION

Data type of the property: Long, indexed

Version of the CA certificate, as a DWORD. The high-order word is the key index, and the low-order word is the CA certificate index.

CR_PROP_CAFORWARDCROSSCERT

Data type of the property: Binary, indexed

The forward cross certificate. A forward cross certificate is a certificate issued upon renewal from the CA to itself signed with CA's previous key. The forward cross certificate has the authority key identifier of the previous CA certificate and the subject key identifier of the new CA certificate.

Applies to root CAs only.

CR_PROP_CAFORWARDCROSSCERTSTATE

Data type of the property: Long, indexed

Whether the forward cross certificate is valid. Valid for root CAs only.

CR_PROP_CANAME

Data type of the property: String

Name of the CA.

CR_PROP_CASIGCERT

Data type of the property: Binary, indexed

CA signing certificate.

CR_PROP_CASIGCERTCHAIN

Data type of the property: Binary, indexed

CA signing certificate chain.

CR_PROP_CASIGCERTCOUNT

Data type of the property: Long

Number of signing certificates for the CA.

CR_PROP_CASIGCERTCRLCHAIN

Data type of the property: Binary, indexed

The CA's signing certificate CRL chain.

CR_PROP_CATYPE

Data type of the property: Long

Type of CA. This can be one of the following values (defined in Certsrv.h):

  • ENUM_ENTERPRISE_ROOTCA
  • ENUM_ENTERPRISE_SUBCA
  • ENUM_STANDALONE_ROOTCA
  • ENUM_STANDALONE_SUBCA
CR_PROP_CAXCHGCERT

Data type of the property: Binary, indexed

CA exchange certificate.

CR_PROP_CAXCHGCERTCHAIN

Data type of the property: Binary, indexed

CA exchange certificate chain.

CR_PROP_CAXCHGCERTCOUNT

Data type of the property: Long

Number of exchange certificates for the CA.

CR_PROP_CAXCHGCERTCRLCHAIN

Data type of the property: Binary, indexed

The CA's exchange certificate CRL chain.

CR_PROP_CERTAIAURLS

Data type of the property: String, indexed

Specifies Authority Information Access URLs as the type of URL requested by a client.

Windows Server 2003:  This flag is not supported.

CR_PROP_CERTCDPURLS

Data type of the property: String, indexed

Specifies CRL Distribution Point URLs as the type of URL requested by a client.

Windows Server 2003:  This flag is not supported.

CR_PROP_CRLSTATE

Data type of the property: Long

State of the CA's CRL. The values can be:

  • CA_DISP_REVOKED
  • CA_DISP_VALID
  • CA_DISP_INVALID
  • CA_DISP_ERROR
CR_PROP_DELTACRL

Data type of the property: Binary, indexed

The CA's delta CRL.

CR_PROP_DELTACRLPUBLISHSTATUS

Data type of the property: Long, indexed

The delta CRL publish status. For more details, see Remarks.

CR_PROP_DNSNAME

Data type of the property: String

The CA's DNS Name.

CR_PROP_EXITCOUNT

Data type of the property: Long

Number of exit modules in use by the CA.

CR_PROP_EXITDESCRIPTION

Data type of the property: String

Description for the exit module.

CR_PROP_FILEVERSION

Data type of the property: String

The Certificate Services file version.

CR_PROP_KRACERT

Data type of the property: Binary, indexed

The CA's key recovery agent (KRA) certificate.

CR_PROP_KRACERTCOUNT

Data type of the property: Long

Number of KRA certificates for the CA.

CR_PROP_KRACERTSTATE

Data type of the property: Long, indexed

The KRA's certificate state. The return value is one of the following:

  • KRA_DISP_EXPIRED
  • KRA_DISP_NOTFOUND
  • KRA_DISP_REVOKED
  • KRA_DISP_VALID
  • KRA_DISP_UNTRUSTED
  • KRA_DISP_NOTLOADED
  • KRA_DISP_INVALID
CR_PROP_KRACERTUSEDCOUNT

Data type of the property: Long

Number of KRA certificates used by the CA.

CR_PROP_PARENTCA

Data type of the property: String

The name of the CA's parent CA.

CR_PROP_POLICYDESCRIPTION

Data type of the property: String

The description for the policy module.

CR_PROP_PRODUCTVERSION

Data type of the property: String

The product version in which the file shipped.

CR_PROP_ROLESEPARATIONENABLED

Data type of the property: Long

Value specifying whether role separation is enabled.

CR_PROP_SANITIZEDCANAME

Data type of the property: String

The sanitized name of the CA. For a definition of a sanitized CA name, see ICertConfig2::GetConfig.

CR_PROP_SANITIZEDCASHORTNAME

Data type of the property: String

The sanitized short name of the CA. For a definition of a sanitized CA short name, see ICertConfig2::GetConfig.

CR_PROP_SHAREDFOLDER

Data type of the property: String

The name of the shared folder directory.

CR_PROP_TEMPLATES

Data type of the property: String

List of templates supported by the CA.

 

PropIndex [in]

If the PropId parameter is indexed, the zero-based index to use when retrieving the property value. If PropId is not indexed, this value is ignored.

PropType [in]

Specifies the type of the property, indicated in the Meaning column of the PropId table. The type can be one of the following types.

ValueMeaning
PROPTYPE_LONG

Signed long data

PROPTYPE_DATE

Date/time (reserved for future use)

PROPTYPE_BINARY

Binary data

PROPTYPE_STRING

Unicode string data

 

Flags [in]

The following flags can be used to specify the format of the returned property value; these flags have meaning only for binary data (such as certificates, certificate chains or certificate revocation lists) and is ignored otherwise.

ValueMeaning
CV_OUT_BASE64

BASE64 without BEGIN/END

CV_OUT_BASE64HEADER

BASE64 with BEGIN CERTIFICATE and END CERTIFICATE

CV_OUT_BASE64REQUESTHEADER

BASE64 with BEGIN NEW CERTIFICATE REQUEST and END NEW CERTIFICATE REQUEST

CV_OUT_BASE64X509CRLHEADER

BASE64 with BEGIN X509 CRL and END X509 CRL

CV_OUT_BINARY

Binary

CV_OUT_HEX

Hexadecimal string

CV_OUT_HEXADDR

Hexadecimal string with address/offset

CV_OUT_HEXASCII

Hexadecimal string with ASCII

CV_OUT_HEXASCIIADDR

Hexadecimal string with ASCII and address/offset

 

pvarPropertyValue [out]

A pointer to a buffer that receives the requested property value. It is a caller's responsibility to free this resource when done by calling VariantClear.

Return value

C++

The return value is an HRESULT. A value of S_OK indicates the method was successful.

VB

The requested property value.

Remarks

The following values are returned when the property identifier is CR_PROP_BASECRLPUBLISHSTATUS or CR_PROP_DELTACRLPUBLISHSTATUS. These values can be combined.

ValueDescription
CPF_BADURL_ERRORA URL is not valid.
CPF_BASEA base CRL was published.
CPF_CASTORE_ERRORA CA store error prevented publication.
CPF_COMPLETEA complete CRL was published.
CPF_DELTAA delta CRL was published.
CPF_FILE_ERRORA file error prevented publication.
CPF_FTP_ERRORAn FTP error prevented publication.
CPF_HTTP_ERRORAn HTTP error prevented publication.
CPF_LDAP_ERRORAn LDAP error prevented publication.
CPF_MANUALA CRL was published manually.
CPF_SHADOWAn empty delta CRL was published, along with a new BASE CRL.
CPF_SIGNATURE_ERRORA signature error prevented publication.

 

For an example of retrieving a CRL, see Retrieving a Certificate Revocation List.

Examples

The following example shows retrieving the signature certificate of the CA. The example assumes the ICertAdmin2 interface pointer is valid.


BSTR bstrCA = NULL;
VARIANT var1;
HRESULT hr;

bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (NULL == bstrCA)
{
    printf("Failed to allocate memory for bstrCA\n");
    exit(1);
}

VariantInit(&var1);
// Retrieve the CA signature certificate at index 0.
hr = pAdmin2->GetCAProperty(bstrCA,
                                CR_PROP_CASIGCERT,
                                0,
                                PROPTYPE_BINARY,
                                CV_OUT_BASE64HEADER,
                                &var1);
if (FAILED(hr))
{
    printf("Failed GetCAProperty\n");
    SysFreeString(bstrCA);
    exit(1);  // Or other error action.
}

// Use the property as needed.
// ...

// Clear the variant when finished.
VariantClear(&var1);
SysFreeString(bstrCA);

Requirements

Minimum supported client

None supported

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Certadm.h (include Certsrv.h)

Library

Certidl.lib

DLL

Certadm.dll

IID

IID_ICertAdmin2 is defined as f7c3ac41-b8ce-4fb4-aa58-3d1dc0e36b39

 

 

Community Additions

ADD
Show:
© 2014 Microsoft