PowerShell PKI Module Documentation
Documentation HomeGet-EnterprisePKIHealthStatus
Synopsis
Get-EnterprisePKIHealthStatus command is an extended console version of Enterprise PKI Health Tool (pkiview.msc MMC snap-in). It is intended to perform Certification Authority health status checking by CA certificate chain status and validating all CRL Distribution Point (CDP) and Authority Information Access (AIA) URLs for each certificate in the chain.
Syntax
Get-EnterprisePKIHealthStatus -CertificateAuthority <CertificateAuthority[]> [-DownloadTimeout <Int32>] [-CaCertExpirationThreshold <Int32>] [-BaseCrlExpirationThreshold <Int32>] [-DeltaCrlExpirationThreshold <Int32>] [-OcspCertExpirationThreshold <Int32>] [<CommonParameters>] Get-EnterprisePKIHealthStatus -Certificate <X509Certificate2[]> [-DownloadTimeout <Int32>] [-CaCertExpirationThreshold <Int32>] [-BaseCrlExpirationThreshold <Int32>] [-DeltaCrlExpirationThreshold <Int32>] [-OcspCertExpirationThreshold <Int32>] [<CommonParameters>]
Description
This command is an extended console version of Enterprise PKI Health Tool (pkiview.msc MMC snap-in). It is intended to perform Certification Authority health status checking by CA certificate chain status and validating all CRL Distribution Point (CDP) and Authority Information Access (AIA) URLs for each certificate in the chain. Depending on a parameter set, different certificate retrieval methods are used.
— if '-CertificateAuthority' parameter is used, the command will attempt to retrieve the most recent "CA Exchange" certificate to use in the validation routine.
— if '-Certificate' parameter is used, the command will use passed certificates directly to use in the validation routine.
The following validation procedures are used by the validation routine:
1. Build certificate chain for each certificate to select trusted anchors and to go through the chain;
2. Retrieve all Issuer URLs from Authority Information Access extension;
2.1. Validate each url (must be either http or ldap) and attempt to download the contents;
2.2. If contents is downloaded, verify whether it is a certificate;
2.2.1. Verify if the downloaded certificate is an issuer for a current certificate;
2.2.2. Validate other certificate properties;
3. Extract URLs from CRL Distribution Points extension;
3.1. Validate each url (must be either http or ldap) and attempt to download the contents;
3.2. If contents is downloaded, verify whether it is a certificate revocation list;
3.2.1. Validate basic CRL properties, such as validity (not yet valid, expired, about to expire);
3.2.2. Validate whether the CRL has valid signature (against CA certificate);
3.3. Do the same for Delta CRLs (if applicable);
4. Extract all Online Certificate Status Protocols (OCSP) URLs from AIA extension;
4.1. Validate OCSP response by sending OCSP request and processing response;
5. Compose status report (managed, I maintain report object and you can access report properties);
6. Repeat steps 2-5 for each subsequent certificate in the chain up to root certificate;
7. Return an array of status objects. Single status object is generated for each certificate chain.
Parameters
-CertificateAuthority <CertificateAuthority[]>
Specifies one or more Enterprise Certification Authoity objects to verify. The command will attampt to download (or request a new one if necessarey) the most recent certificate based on "CA Exchange" certificate template. This certificate will be used to construct the chain, retrieve and validate CRL Distribution Points (CDP) and Authority Information Access (AIA) URLs for entire chain.
| Required? | True |
| Position? | named |
| Default value | |
| Accept pipeline input? | true (ByValue, ByPropertyName) |
| Accept wildcard characters? | False |
-DownloadTimeout <Int32>
Specifies the URL download timeout in seconds. Default value is 15 seconds.
| Required? | False |
| Position? | named |
| Default value | 15 |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-CaCertExpirationThreshold <Int32>
Specifies the CA certificate expiration threshold in percents. If CA certificate validity reaches this threshold value, CA certificate status is marked "Expiring" which indicate that in near future it will expire, and CA server administrators should take care on CA certificate renewal or replacement.
| Required? | False |
| Position? | named |
| Default value | 80 |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-BaseCrlExpirationThreshold <Int32>
Specifies the Base CRL expiration threshold in percents. If Base CRL certificate validity reaches this threshold value, its status is marked "Expiring" which indicate that in near future CRL will expire. Enterprise CAs automatically renew their CRLs in the CRL distribution points and no additional steps are required.
For Standlone, offline and 3rd party CAs, manual steps for Base CRL renewal and publication to defined CRL distribution points may be required.
| Required? | False |
| Position? | named |
| Default value | 80 |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-DeltaCrlExpirationThreshold <Int32>
Specifies the Delta CRL expiration threshold in percents. If Delta CRL certificate validity reaches this threshold value, its status is marked "Expiring" which indicate that in near future CRL will expire. Enterprise CAs automatically renew their CRLs in the CRL distribution points and no additional steps are required.
For Standlone, offline and 3rd party CAs, manual steps for Delta CRL renewal and publication to defined CRL distribution points may be required.
| Required? | False |
| Position? | named |
| Default value | 80 |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-OcspCertExpirationThreshold <Int32>
Specifies the Online Cetificate Status Protocol (OCSP) signing certificate expiration threshold in percents. If OCSP certificate validity reaches this threshold value, CA certificate status is marked "Expiring" which indicate that in near future it will expire, and OCSP server administrators should take care on CA certificate renewal or replacement.
| Required? | False |
| Position? | named |
| Default value | 80 |
| Accept pipeline input? | false |
| Accept wildcard characters? | False |
-Certificate <X509Certificate2[]>
Specifies one or more certificate objects to verify. The command will use this certificate to construct the chain, retrieve and validate CRL Distribution Points (CDP) and Authority Information Access (AIA) URLs for entire certificate chain.
| Required? | True |
| Position? | named |
| 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.CertificateAuthority[]
This parameter set is used to validate existing Enterprise CA
Security.Cryptography.X509Certificates.X509Certificate2[]
This parameter set is used to validate Standalone and 3rd party CAs.
Outputs
PKI.EnterprisePKI.CAObject[]
Notes
Examples
Example 1
PS C:\> Get-CA | Get-EnterprisePKIHealthStatus
This example will enumerate all Enterprise Certification Authorities in the Active Directory forest and validate their chains and CDP/AIA URLs for accessibility and validity.
Example 2
PS C:\> $cert = New-Object Security.Cryptography.X509Certificates.X509Certificate2 "C:\certs\leafcert.cer" PS C:\> Get-EnterprisePKIHealthStatus -Certificate $cert -CaCertExpirationThreshold 90 -BaseCrlExpirationThreshold 90 -DeltaCrlExpirationThreshold 70
This example will instantiate an 'X509Certificate2' object from a certificate file and validate entire chain for validity and health. CA certificate and Base CRL will be considered 'Expiring' when certificate reaches 90% of its validity and Delta CRL when it reaches 70% of its validity.
Related links
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