Hello world! Here is the fifth and the last part of an "AD CS Partitioned CRLs - A Comprehensive Guide" blog post series.

All posts in this series:

• Part 1 - Introduction
• Part 2 - Design Strategies
• Part 3 - Configuration Components
• Part 4 - Recipe Guide
• Part 5 - Partitioned CRL API and Events (current)

In this post, I will cover new programming APIs changes in existing API and Windows Event Log events associated with partitioned CRLs.

Partitioned CRL APIs

All AD CS programming APIs refer to ICertRequest2 and ICertAdmin2 COM interfaces, which are main interfaces to interact with AD CS servers.

New APIs

 ICertRequest2/ICertAdmin::GetCAProperty received several new PropID parameters that allow to access per-partition CRLs and their publishing statuses.

All new APIs work only when partitioned CRLs are globally enabled. If partitioned CRLs are not enabled, all mentioned below APIs will fail with HRESULT=0x80070057.

• PropID = 0x0000002E (CR_PROP_CRLPARTITIONCOUNT) "CRL Partitions Count"

Returns the number of configured CRL partitions.

PowerShell example:

$CR_PROP_CRLPARTITIONCOUNT = 0x2E
$CertRequest = New-Object -com CertificateAuthority.Request
$CertRequest.GetCAProperty("caHostName\caName", $CR_PROP_CRLPARTITIONCOUNT, 0, 1, 0)

Certutil counterpart:

Certutil -getreg CA\CRLPartitionCount

• PropID = 0x0000002F (CR_PROP_PARTITIONED_BASECRL) "Partitioned Base CRL"

Returns a Base CRL for specified CA key and partition index.

PowerShell example:

function Get-PropIndex([Int16]$KeyID, [Int16]$PartitionID) {
    ($PartitionID -shl 16) -bor $KeyID
}
$CR_PROP_PARTITIONED_BASECRL = 0x2F
$CertRequest = New-Object -com CertificateAuthority.Request
$PropIndex = Get-PropIndex $KeyID $PartitionID
$CertRequest.GetCAProperty("caHostName\caName", $CR_PROP_PARTITIONED_BASECRL, $PropIndex, 3, 1)

Base CRL is returned in a Base64-encoded string with CR/LF line endings. Note that 3rd argument is a composite DWORD where upper WORD represents partition index and lower WORD represents CA key index. The Get-PropIndex function constructs proper value for $PropIndex variable.

• 0x00000030 (CR_PROP_PARTITIONED_DELTACRL) "Partitioned Delta CRL"

PowerShell example:

function Get-PropIndex([Int16]$KeyID, [Int16]$PartitionID) {
    ($PartitionID -shl 16) -bor $KeyID
}
$CR_PROP_PARTITIONED_DELTACRL = 0x30
$CertRequest = New-Object -com CertificateAuthority.Request
$PropIndex = Get-PropIndex $KeyID $PartitionID
$CertRequest.GetCAProperty("caHostName\caName", $CR_PROP_PARTITIONED_DELTACRL, $PropIndex, 3, 1)

Delta CRL is returned in a Base64-encoded string with CR/LF line endings. Note that 3rd argument is a composite DWORD where upper WORD represents partition index and lower WORD represents CA key index. The Get-PropIndex function constructs proper value for $PropIndex variable.

CR_PROP_PARTITIONED_DELTACRL PropID will fail if Delta CRLs are not enabled on CA server.

• PropID = 0x00000031 (CR_PROP_PARTITIONED_BASECRLPUBLISHSTATUS) "Partitioned Base CRL Publishing Status"

Returns  the publishing status of a particular partitioned base CRL.

PowerShell example:

function Get-PropIndex([Int16]$KeyID, [Int16]$PartitionID) {
    ($PartitionID -shl 16) -bor $KeyID
}
$CR_PROP_PARTITIONED_BASECRLPUBLISHSTATUS = 0x31
$PropIndex = Get-PropIndex $KeyID $PartitionID
$CertRequest = New-Object -com CertificateAuthority.Request
$CertRequest.GetCAProperty("caHostName\caName", $CR_PROP_PARTITIONED_BASECRLPUBLISHSTATUS, $PropIndex, 1, 0)

Return value is a number that is a combination of values in the following table:

Table 1: CRL Publish Statuses

• PropID = 0x00000032 (CR_PROP_ PARTITIONED_DELTACRLPUBLISHSTATUS) "Partitioned Delta CRL Publishing Status"

Returns  the publishing status of a particular partitioned partitioned CRL.

PowerShell example:

function Get-PropIndex([Int16]$KeyID, [Int16]$PartitionID) {
    ($PartitionID -shl 16) -bor $KeyID
}
$CR_PROP_PARTITIONED_DELTACRLPUBLISHSTATUS = 0x32
$PropIndex = Get-PropIndex $KeyID $PartitionID
$CertRequest = New-Object -com CertificateAuthority.Request
$CertRequest.GetCAProperty("caHostName\caName", $CR_PROP_PARTITIONED_DELTACRLPUBLISHSTATUS, $PropIndex, 1, 0)

Return value is a number that is mapped to values in the Table 1.

CR_PROP_ PARTITIONED_DELTACRLPUBLISHSTATUS PropID will fail if Delta CRLs are not enabled on CA server.

Existing API changes

The following PropIDs changed in ICertRequest2/ICertAdmin::GetCAProperty API:

• PropID = 0x00000011 (CR_PROP_BASECRL) "Base CRL"
• PropID = 0x00000012 (CR_PROP_DELTACRL) "Delta CRL"
• PropID = 0x0000001E (CR_PROP_BASECRLPUBLISHSTATUS) "Base CRL Publishing Status"
• PropID = 0x0000001F (CR_PROP_DELTACRLPUBLISHSTATUS) "Delta CRL Publishing State"

They fail if partitioned CRLs are enabled and partition zero is configured to be exclusively a partition rather than an aggregate CRL. Though, they may continue to work while there is active aggregated CRL in CA database.

• PropID = 0x00000029 (CR_PROP_CERTCDPURLS) "CRL Distribution Points"

When no partitioned CRL is enabled, or partitioning enabled and partition zero is aggregated (non-exclusive), this property returns CDP URLs to be published in issued certificates. It will strip <CRLPartitionIndex> variable. Basically, it will behave in same way it did before under these conditions.

When partitioned CRLs are enabled and partition zero is exclusive (non-aggregated), this property returns URL template with URL-encoded <CRLPartitionIndex> as literal string, i.e. %3CCRLPartitionIndex%3E. Other URL variables will be expanded.

Partitioned CRL Windows Event Log events

There are several events associated with partitioned CRL, specifically, related to misconfiguration. Tables below provide event metadata information.

Event ID = 139

<template xmlns="http://schemas.microsoft.com/win/2004/08/events">
  <data name="CACommonName" inType="win:UnicodeString" outType="xs:string"/>
</template>

Event ID = 140

<template xmlns="http://schemas.microsoft.com/win/2004/08/events">
  <data name="CACommonName" inType="win:UnicodeString" outType="xs:string"/>
</template>

Event ID = 141

<template xmlns="http://schemas.microsoft.com/win/2004/08/events">
  <data name="CACommonName" inType="win:UnicodeString" outType="xs:string"/>
</template>

Event ID = 143

<template xmlns="http://schemas.microsoft.com/win/2004/08/events">
  <data name="CACommonName" inType="win:UnicodeString" outType="xs:string"/>
</template>

Event ID = 144

Event ID = 146

<template xmlns="http://schemas.microsoft.com/win/2004/08/events">
  <data name="CACommonName" inType="win:UnicodeString" outType="xs:string"/>
</template>