PowerShell PKI Module Documentation

This command requires installed Remote Server Administration Tools (RSAT)

Add-AuthorityInformationAccess

Synopsis

Adds new Certification Authority Authority Information Access (AIA) paths.

Syntax

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

Description

Adds new Certification Authority Authority Information Access (AIA) paths. This command doesn't change actual settings, but just prepares AIA URIs.

Authority Information Access (AIA) extension is used to specify issuer's resources location like CRT file and/or Online Certificate Status Protocol (OCSP) URIs in the issued certificates AIA extension.

When you define CRT file URIs it can be used by certificate chaining engine to retrieve particular certificate's issuer certificate. If an URI is missing or broken, certificate verification may fail and the certificate would be rejected. This command don't support physical CRT file publishing options, as the result you need to manually copy a file to the target locations. Original CRT file is placed in %windir%\system32\certsvc\certenroll folder. You may specify multiple URIs for redundancy. URIs are checked in the same order as they are placed in the certificate's AIA extension until issuer's certificate 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 CRT location URIs. This is because if the first two URIs fails, client will fail chain building due to a timeout and certificate would be rejected.

OCSP URI can be used by a clients to determine certificate revocation status. Unlike CRLs, OCSP consume very little network traffic (about 2kb for request and response). Currently only HTTP protocol is supported by OCSP locations. In Windows Vista and newer systems OCSP has higher priority than CRLDistributionPoints extension. Thus OCSP URIs are processed first. OCSP URIs has their own precedence rules, thus OCSP URIs are checked in the same order as they are placed in the certificate's AIA extension until revocation status is determined. It doesn't matter whether OCSP URIs are placed prior or after CRT file location URIs, because they are grouped in a different access methods. Here is an example:

[1]Authority Info Access
     Access Method=On-line Certificate Status Protocol (1.3.6.1.5.5.7.48.1)
     Alternative Name:
         URL=http://eu.company.com/ocsp
         URL=http://na.company.com/ocsp
[2]Authority Info Access
     Access Method=Certification Authority Issuer (1.3.6.1.5.5.7.48.2)
     Alternative Name:
         URL=http://eu.company.com/MyCA.crt
         URL=http://na.company.com/MyCA.crt

in a given example even if CRT file URIs are placed after OCSP URIs certificate chaining engine will use Certification Authority Issuer's URIs first during chain building. The frist URI http://eu.company.com/MyCA.crt will be used. If it fails, http://na.company.com/MyCA.crt will be used.

Parameters

-InputObject <AuthorityInformationAccess[]>

Specifies the AuthorityInformationAccess object to which new CRT distribution points are added. This object can be retrieved by running Get-AuthorityInformationAccess command.

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

-URI <String[]>

Specifies new CRT file publishing points for specified CA server. 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 CRT's to this location. This flag is deprecated and can be used only with default local path.
2 – Include in the AIA extension of issued certificates.
32 – Include in the Online Certificate Status Protocol (OCSP) extension.

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
%4 – CA's certificates 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 the following characters removed: \/:\*?"<>|
%11 – indicates that CA certificate is certificate object in AD CS

With Windows CA you should assert %4 variable within URI. This is important when you renew CA's certificate. After CA certificate renewal, CA server will maintain both certificates, previous and renewed. To differentiate them, CA server will include certificate index in the parentheses. For example you have specified the following URI: 2:http://eu.company.com/MyCA%4.crt
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.crt
Once CA certificate is renewed, CA certificate will generate new CRT file with corresponding index and in newly issued certificates the following URI will be published: http://eu.company.com/MyCA(1).crt
Subsequent CA certificate renewals will cause URI update accordingly.

This allows clients to build correct certificate chains for previously and newly issued certificates. Also you don't need to change CRT file location after CA certificate renewal, because CA server will automatically place correct CA certificate file name.

Note: Windows PKI supports the following URI formats.
for CA certificate publishing:
ldap:///<DirectoryAccessProtocolPath>
UNC or absolute physical paths are no longer supported.

for CA certificate retrieval:
http://<DomainURL>/<VirtualDirectoryAndFilePath>.crt
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.AuthorityInformationAccess

Outputs

PKI.CertificateServices.AuthorityInformationAccess

Notes

Examples

Example 1

PS C:\> Get-CertificationAuthority -Name MyCA | Get-AIA | Add-AuthorityInformationAccess -URI "2:http://eu.company.com/MyCA%4.crt" | Set-AuthorityInformationAccess -RestartCA

This example will retrieve AIA extension configuration from 'MyCA' CA server and adds new URI that will be published in all issued certificates. After configuration is changed, the command will restart certificate services to immediately apply changes.

Example 2

PS C:\> Get-CertificationAuthority -Name RootCA | Get-AuthorityInformationAccess | Add-AuthorityInformationAccess -URI "32:http://na.company.com/OCSP" | Set-AuthorityInformationAccess -RestartCA

This example will retrieve AIA extension configuration from 'RootCA' CA server and adds new URI that will be published in all issued certificates as OCSP location. After configuration is changed, the command will restart certificate services 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