PowerShell PKI Module Documentation

This command requires installed Remote Server Administration Tools (RSAT)

Add-CRLDistributionPoint

Synopsis

Adds new CRL distribution points (CDP) to a specified Certification Authority.

Syntax

Add-CRLDistributionPoint [-InputObject] <CRLDistributionPoint[]> [-URI] <String[]> [<CommonParameters>]

Description

Adds new CRL distribution points (CDP) to a specified Certification Authority. This command doesn't change actual settings, but just prepares the CDP URIs.

CDP Extension consist of two URI types:

— for physical CRL file publishing. These URIs are not appeared in the certificate CDP extension.
— for publishing in the certificate/CRL appropriate extensions.

Published URIs are used by certificate chaining engine during certificate revocation status checking. URIs are checked in the same order as they are placed in the certificate's CDP extension until CRL is retrieved. The most accessible URI should be placed first. This command adds new URIs below existing URIs. It is recommended to specify no more than two CRL location URIs (for Base CRLs). This is because if the first two URIs fails, client will fail revocation checking due of timeout and certificate might be rejected. Here is an example:

[1]CRL Distribution Point
     Distribution Point Name:
         Full Name:
             URL=http://eu.company.com/MyCA.crl
             URL=http://na.company.com/MyCA.crl

In a given example http://eu.company.com/MyCA.crl is processed first. If this URI fails, http://na.company.com/MyCA.crl will be used. If both URIs fails, client application should report 'Revocation offline' error.

Note: If certificate's AIA extension contains OCSP URIs and client application supports OCSP, it is used first. Otherwise CDP extension is used. If all OCSP locations fail, CDP extension is used. In certain cases applications (for example CryptoAPI) that supports OCSP may elect to ignore OCSP and use CDP extension instead. Thus it is very important to maintain correct and actual URIs in the CDP extension.

Parameters

-InputObject <CRLDistributionPoint[]>

Specifies the CRLDistributionPoint object to which add new CRL distribution points. This object can be retrieved by running Get-CRLDistributionPoint command.

Required?	True
Position?	0
Default value
Accept pipeline input?	true (ByValue, ByPropertyName)
Accept wildcard characters?	False

-URI <String[]>

Specifies new CRL file publishing distribution points for particular CA. Must be passed in the following format: <Flags>:<RelativeURI>, where <Flags> is a combination of publishing flags. The following values are possible for <Flags>:

1 – Publish CRLs to this location.
2 – Include in all issued certificates.
4 – Include in CRLs. Clients use this to find delta CRL locations.
8 – Include in the CDP extension of CRLs.
64 – Publish delta CRLs to this location. Specifies where to publish in AD DS when publishing to LDAP URLs.
128 – Include in the IDP extension of issued CRLs.

Within <RelativeURI> you can use the following variables:

%1 – the CA's computer DNS name.
%2 – the CA's computer NetBIOS name.
%3 – CA's logical name.
%6 – the LDAP path of the forest's configuration naming context for the forest.
%7 – CA's 'sanitized' name. This is the same as CA name but with encoded special characters, such: \/:\*?"<>|.
%8 – the CRL's renewal extension.
%9 – indicates whether Delta CRLs are supported by this CA.
%10 – indicates that the object is CDP object in AD CS.

With Windows CA you should assert %8 variable within URI. It is important when you renew CA's certificate with new key pair. After CA certificate renewal CA server will maintain both CRLs that are signed by previous and renewed CA certificate. To separate them CA server will include certificate index in the parenthesises. For example you have specified the following URI: 6:http://eu.company.com/MyCA%8.crl
In a given example CA server with initial CA certificate will publish the following URI in the issued certificates AIA extension: http://eu.company.com/MyCA.crl
Once CA certificate is renewed with new key pair, CA certificate will generate new CRLs files with corresponding index and in newly issued certificates the following URI will be published: http://eu.company.com/MyCA(1).crl
Subsequent CA certificate renewals with new key pair will cause URI update accordingly.

Note: Windows PKI supports the following URI formats.
for CRL publishing
<DriveLetter>:\<FilePath>.crl
file://\<RemoteServerName>\<ShareName>\<FilePath>.crl
\<RemoteServerName>\<ShareName>\<FilePath>.crl
ldap:///<DirectoryAccessProtocolPath>

for CRL retrieval:
http://<DomainURL>/<VirtualDirectoryAndFilePath>.crl
ldap:///<DirectoryAccessProtocolPath>
ldap://<hostname>/<path>?<query>

Note: ldap:///<DirectoryAccessProtocolPath> URI type assumes Active Directory usage and must contain forest root domain domain component (DC=…) within LDAP path. This may cause big retrieval delays. Since Active Directory may contain many domain controllers and specified in LDAP URI content is automatically replicated between all domain controllers in the current forest. To simplify content retrieval from Active Directory CryptoAPI may not contact forest root domain, but contact nearest to client domain controller. Nearest domain controller is placed in $env:LogonServer system variable (or %LogonServer% in CMD syntax).

Also Windows PKI supports another form of LDAP URIs with host name:
ldap://<hostname>/path?query

In this case client will not contact domain controller, but specified host directly. Unlike ldap:/// URI form, ldap://<hostname> may use 3rd party LDAP-compatible directory. Automatic content (CA certificate or certificate revocation list) publishing to such directories is not supported. You will have to manually publish CA certificates to these directories by using external means.

Required?	True
Position?	1
Default value
Accept pipeline input?	false
Accept wildcard characters?	False

<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, InformationAction, InformationVariable,
WarningAction, WarningVariable, OutBuffer, PipelineVariable and OutVariable.
For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

Inputs

PKI.CertificateServices.CRLDistributionPoint

Outputs

PKI.CertificateServices.CRLDistributionPoint

Notes

Examples

Example 1

PS C:\> Get-CertificationAuthority RootCA | Get-CrlDistributionPoint | Add-CrlDistributionPoint -NewURI "6:http://crl.domain.com/%3%8%9.crl" | Set-CrlDistributionPoint -RestartCA

This example will add new CDP URI to certificate CDP for 'RootCA' CA server. Also this will add new URI in Freshest CRL in CRL CDP to locate corresponding Delta CRL. After command completion CA services will be restarted to immediately apply changes.

Example 2

PS C:\> Get-CertificationAuthority | Get-CrlDistributionPoint | Add-CrlDistributionPoint -NewURI "65:\\ServerName\crlfile%9.crl", "65:C:\CertData\%3%8%9.crl" | Set-CrlDistributionPoint -RestartCA

This will add new paths for Base and Delta CRL file publication for all CAs in the current forest. This example will not add any new URIs in certificate CDP extension, but instructs CA to publish physical CRL files to the specified locations. After command completion CA services will be restarted to immediately apply changes.

Minimum PowerShell version support

Windows PowerShell 3.0

Operating System Support

Windows 7
Windows 8
Windows 8.1
Windows 10
Windows 11
Windows Server 2008 R2 all editions
Windows Server 2012 all editions
Windows Server 2012 R2 all editions
Windows Server 2016 all editions
Windows Server 2019 all editions
Windows Server 2022 all editions