ICertServerExit::GetCertificateProperty method (certif.h)

Article
07/27/2022

The GetCertificateProperty method returns a named property from a certificate.

Syntax

HRESULT GetCertificateProperty(
  [in]  const BSTR strPropertyName,
  [in]  LONG       PropertyType,
  [out] VARIANT    *pvarPropertyValue
);

Parameters

[in] strPropertyName

Specifies the named property to retrieve. There is a stock set of certificate properties, referred to as the name properties, that are always valid and can be retrieved by calling this method. For information about these properties, see Name Properties. Other properties that can be retrieved include the certificate properties.

The following properties are unique to certificates and can be read by GetCertificateProperty.

Value	Meaning
NotBefore Date/Time	Certificate start validity date
NotAfter Date/Time	Certificate expiration date
PublicKeyAlgorithm String	Subject key algorithm object identifier (OID)
RawCertificate Binary	Raw certificate bytes
RawPublicKey Binary	Subject key
RawPublicKeyAlgorithmParameters Binary	Subject key algorithm parameters
RequestID Signed Long	Internal request ID
SerialNumber String	Certificate serial number

The certificate's DistinguishedName, RawName, and SerialNumber properties are accessible by GetCertificateProperty only after the policy module has finished processing the request and the certificate is issued.

The following properties apply to the certification authority. The context must be zero to read any of these properties. The context is set to zero when the ICertServerExit object is initially created. It can also be set to zero by invoking the SetContext method.

Value	Meaning
CAType Long	Type of certification authority. This can be one of the following values (defined in Certsrv.h): ENUM_ENTERPRISE_ROOTCA ENUM_ENTERPRISE_SUBCA ENUM_STANDALONE_ROOTCA ENUM_STANDALONE_SUBCA
CertCount Long	Number of CA certificates. This value will be one plus the number of times that the CA has been renewed. For information about renewal, see Certification Authority Renewal.
CertState Long	CA certificate state. This can be one of the following values: CA_DISP_ERROR: The CA certificate was never issued. CA_DISP_REVOKED: The CA certificate has been revoked. CA_DISP_VALID: The CA certificate is still valid. CA_DISP_INVALID: The CA certificate has expired. This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
CertSuffix String	Suffix for the CA certificate. The suffix is an empty string for CA certificates with an index of zero; otherwise, the suffix (in the form of "(nn)", where nn is the certificate index) is applied to all URLs that point to CA certificates stored in files or directory service objects. For non-LDAP URLs, the suffix typically appears before the ".crt" text. For LDAP URLs, the suffix is typically appended to the first 'CN=' in the full distinguished name. This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
CRLIndex Long	Certificate revocation list (CRL) index. Appending a certificate index to this property name allows you to retrieve the CRL index. The CRL index does not necessarily match the certificate index. For more information, see Certification. This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
CRLState Long	CRL state. This can be one of the following values: CA_DISP_ERROR: The CRL is managed by another CA certificate. CA_DISP_REVOKED: All unexpired CA certificates that use this CA certificate's CRL have been revoked. CA_DISP_VALID: The CA certificate is still being used to publish CRLs as needed. CA_DISP_INVALID: All CA certificates that use this CA certificate's CRL are expired. This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
CRLSuffix String	Suffix for the CA CRL. The suffix is an empty string for CRLs with an index of zero; otherwise, the suffix (in the form of "(nn)", where nn is the CRL index) is applied to all URLs pointing to CRLs stored in files or directory service objects. For non-LDAP URLs, the suffix typically appears before the ".crl" text. For LDAP URLs, the suffix typically is appended to the first 'CN=' in the full distinguished name. This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
fUseDS Long	Indicates whether the CA uses a directory service. This can be either of the following values: 0=no 1=yes
MachineDNSName String	DNS name of server hosting the CA.
ModuleRegistryLocation String	Registry location available for use by the module.
RawCACertificate Binary	CA certificate. This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
RawCRL Binary	CA's certificate revocation list (CRL). This property name may be appended with '.#', where # represents a CA certificate index (or, in the case of the CRLSuffix property, a CRL index). For information about certificate and CRL indices, see Certification Authority Renewal.
RequesterCAAccess Long	Indicates whether the requester is authorized to request the certificate. This can be either of the following values: 0=no 1=yes (The Certification Authority MMC snap-in can be used to control certificate request permissions.)
SanitizedCAName String	Sanitized name for the CA. For information about sanitized CA names, see ICertConfig::GetConfig.
SanitizedShortName String	Sanitized name for the CA, shortened and containing a hash value to ensure uniqueness.

[in] PropertyType

Specifies the property type. The type can be one of the following.

Value	Meaning
PROPTYPE_LONG	Signed long data
PROPTYPE_DATE	Date/time
PROPTYPE_BINARY	Binary data
PROPTYPE_STRING	Unicode string data

[out] pvarPropertyValue

A pointer to a VARIANT that will contain the property value. The returned value is encoded as a BSTR. Use the SysStringByteLen function to retrieve the length of the BSTR. The binary BLOB is stored as a Distinguished Encoding Rules encoded X.509 certificate.

Return value

C++

If the method succeeds, the method returns S_OK.

If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

VB

The return value is the requested property value.

Remarks

You must call ICertServerExit::SetContext prior to using this method.

Examples

BSTR    bstrPropName = NULL;
VARIANT varProp;

VariantInit(&varProp);

// Set the property name to RequestID.
bstrPropName = SysAllocString(L"RequestID");

// Retrieve the certificate property.
// pCertServerExit has been used to call SetContext previously.
hr = pCertServerExit->GetCertificateProperty(bstrPropName,
                                             PROPTYPE_LONG,
                                             &varProp );
if (FAILED(hr))
{
    printf("Failed GetCertificateProperty [%x]\n", hr);
    goto error;
}
else
{
    // Successfully retrieved property; use varProp as needed.
    // ...
}

// Done processing.
if (NULL != bstrPropName)
    SysFreeString(bstrPropName);
VariantClear(&varProp);

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	certif.h (include Certsrv.h)
Library	Certidl.lib
DLL	Certcli.dll

Share via