ConfirmACMERenewalReadiness - RIT-ITS/CertifiCat-PS GitHub Wiki
Determines the readiness of a certificate to be renewed / replaced via the ACME server.
Confirm-ACMERenewalReadiness [-DomainName <String>]
[-RenewalMethod (PA/IIS/Directory)] [-RenewalDirectory <String>]
[-BindingPorts <String[]>] [-RenewalThreshold <Int>] [-debugEnabled]
[-debugLogDirectory <string>] [-debugMode <string>]Queries for certificates in a variety of manners in order to determine if a new renewal order should be placed. Certificates that are found that expire 14 or more days in the future are determined to be "not ready" for renewal.
This function is primarily called as part of the Initialize-NewACMECertificate function, but can also be called directly in cases where an administrator wishes to only verify certificate expiry.
When this command is run directly, output is returned informationally; when the command is run as part of the Initialize-NewACMECertificate function, the result can (depending on configuration) block the new ACME certificate from being requested.
If the function detects that it is being used in a PowerShell 7+ console, it will suspend, and output a command that can be run in a legacy PowerShell console instead. See the Parameters list below for affected parameters and parameter values (generically, this applies to anything related to IIS or bindings).
📄 Note: This is the default behavior when no specific RenewalMethod is specified
Confirm-ACMERenewalReadiness -DomainName web.example.comThis command will use the Posh-ACME working directory to locate an active, non-expired certificate whose subject contains the domain name value specifed.
Confirm-ACMERenewalReadiness -DomainName web.example.com -RenewalMethod IISThis command will query all HTTPS bindings in IIS and alert if any of the associated certificates (whose subject contains the domain name value specifed) are active and ineligible for renewal.
Confirm-ACMERenewalReadiness -DomainName web.example.com -RenewalMethod IIS -BindingPorts 443, 8081This command will query the bindings in IIS associated with the specified port(s) and alert if any of the associated certificates (whose subject contains the domain name value specifed) are active and ineligible for renewal.
Confirm-ACMERenewalReadiness -DomainName web.example.com -RenewalMethod Directory -RenewalDirectory c:\myCertsThis command will recursively query the directory specified, for any public key (*.cer) file and alert if any of the associated certificates (whose subject contains the domain name value specifed, and whose issuer contains 'incommon') are active and ineligible for renewal.
The primary domain name associated with the certificate (e.g. in the Subject field).
Type: String
Position: 1 / Named
Default Value: False
Required: True
The mechanism to use to search for the existing certificates.
Type: String
Position: Named
ValidateSet: PA, IIS, Directory
Default Value: PA
Required: False
If the function detects this parameter value being used in a PowerShell 7+ console, it will suspend, and output a command that can be run in a legacy PowerShell console instead.
When the RenewalMethod is "Directory," this specifies the directory in which to recursively look for certificates issued by InCommon with the subject containing the main domain.
Type: String
Position: Named
Default Value: c:\its\certs\posh-acme
Required: False
When the RenewalMethod is "IIS," this optionally allows the function to look for certificates only associated with the provided port(s).
Type: String[]
Position: Named
Default Value: False
Required: False
Specifies the number of days prior to the expiration of the current certificate needed before a request for a new certificate will be sent.
Type: Int
Position: Named
Default Value: False
Required: False
This switch must be present to cause the function in question to output the contents of the object to a file or event log
Type: Switch
Position: Named
Required: False
Specifies where the CertifiCat-PS debug logs are written, when the debugMode option is EVT or Both.
Type: String
Position: Named
Required: False
Controls where the CertifiCat-PS debug informaiton is written: EVT (the windows event log), File (a text file on disk), or Both (a text file on disk and the Windows Event Log)
Type: String
Position: Named
Required: False
Default Value: EVT
ValidateSet: EVT, File, Both
Returns a custom PowerShell object with properties about the function and the account that was set up. The object has the following properties:
| Property | Details |
|---|---|
| FunctionName | Name of the function that was run |
| RunningPSVersion | The version of the PowerShell console used to run the function |
| PS5Command | A full string containing the commands needed to run the same command in PowerShell 5 |
| FunctionArguments | A list of the arguments passed to the function |
| FunctionSuccess | True/False indicating if the function succeeded. When false, this typically indicates a larger issue (e.g. no admin rights, etc) |
| Errors | A string containing details about any errors that were encountered |
| Bindings | If the RenewalMethod is IIS, this will populate with an array of Web Binding objects that can be further analyzed. See Get-WebBinding. |
| Certificates | Depending on the RenewalMethod chosen, this will be an array of either PoshACME.PACertificate objects (if the RenewalMethod = PA), or System.Security.Cryptography.X509Certificates.X509Certificate2 objects if the RenewalMethod is IIS or Directory. These objects can be further analyzed as needed |
| ReadyForRenewal | A True/False indicating whether or not the certificate issued to the main domain should be renewed or not |
| RenewalThreshold | The value provided as the minimum number of days required before expiration for a new certificate to be issued |
| debugEnabled | Boolean indicating whether debug logging was enabled |
| debugLogDirectory | String indicating the location of the debug log file, if file logging mode is enabled |
| debugMode | String indicating the logging mode (i.e. EVT, File, or Both) |