PowerShell PKI Module Documentation

This command requires installed Remote Server Administration Tools (RSAT)

Revoke-Certificate

Synopsis

Revokes specified certificate request with a specified reason.

Syntax

Revoke-Certificate [-Request] <Object> [[-Reason] <String> {Unspecified | KeyCompromise | CACompromise | AffiliationChanged | Superseded | CeaseOfOperation | Hold | Unrevoke} ] [[-RevocationDate] <DateTime>] [<CommonParameters>]

Description

Revokes specified certificate request with a specified reason. A revoked certificate will appear in a subsequent certificate revocation lists (CRLs), provided the revocation date is effective at the time the CRL was published.

It is possible to use this command more than once on the same certificate, which allows you to change the effective revocation date and revocation reason.

Parameters

-Request <Object>

Specifies the particular request object. Request objects can be retrieved by running one of the following commands:
Get-IssuedRequest
Get-RevokedRequest

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

-Reason <String>

Specifies a reason why certificate was revoked. This parameter accepts one of the following values:

Unspecified – (default) is used if the certificate is revoked for a reason outside the scope of supported reasons.
KeyCompromise – is used if the certificate private key was stolen or become known to an unauthorized entity.
CACompromise – is used if the CA certificate private key was stolen or become known to an unauthorized entity.
AffiliationChanged – is used when employee (or other entity) has changed its affiliation (job position) and current certificates are no longer required in new position.
Superseded – is used when a new certificate version (for example with new issuance, application policy or with updated extensions) is available and previous (but still valid) certificate must not be used.
CeaseOfOperation – is used when an employee leaves a company, or device is decommissioned.
Hold – is used to temporarily revoke certificate. For example when an employee is in a vacation.
Unrevoke – is used to release a certificate from CRL. If a certificate has been revoked with any reason code other than 'Hold', it cannot be reinstated.

Note: do not use 'Hold' reason, especially for signing certificates. This is because it is not possible to determine whether the certificate was valid at a signing time (determined by a timestamp in the signature).

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

-RevocationDate <DateTime>

Provides the date on which it is known or suspected that the private key was compromised or that the certificate otherwise became invalid. This date may be earlier than the revocation date in the CRL entry, which is the date at which the CA processed the revocation. When a revocation is first posted by a CRL issuer in a CRL, the invalidity date may precede the date of issue of earlier CRLs, but the revocation date should not precede the date of issue of earlier CRLs.

The parameter must be set as a valid datetime string. Valid string may vary depending on current regional settings. For example, the following format is used in Latvia:

MM.dd.yyyy hh:mm:ss
MM – month (2 digits)
dd – day (2 digits)
yyyy – year (4 digits)
hh – hours (2 digits)
mm – minutes (2 digits)
ss – seconds (2 digits)

For more details about datetime format in your region see more in Control Panel\Regional and Language applet.

Required?	False
Position?	2
Default value	[DateTime]::Now
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

SysadminsLV.PKI.Management.CertificateServices.Database.AdcsDbRow

Outputs

SysadminsLV.PKI.Utils.IServiceOperationResult

Notes

Examples

Example 1

PS C:\> Get-CertificationAuthority CompanyCA | Get-IssuedRequest -Filter "CommonName -eq www.company.com" | Revoke-Certificate -Reason "CeaseOfOperation"

Revokes all certificates issued to www.company.com. This will guarantee that no one will use decommissioned web server certificate to impersonate legitimate server.

Example 2

PS C:\> Get-CertificationAuthority | Get-Issuedrequest -Filter "CommonName -gt users vpodans" | Revoke-Certificate -Reason "CeaseOfOperation" -RevocationDate "05.01.2011"

Revokes all certificates issued to 'vpodans' user account stored in Users organizational unit and set revocation date to 01 May 2011.

Example 3

PS C:\> Get-CertificationAuthority MyCA | Get-RevokedRequest -ID 17 | Revoke-Certificate -Reason "KeyCompromise"

This command will update revocation reason for request with ID=17 and set reason to "KeyCompromise".

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