Free Webinar - Is Your PKI Healthy? The Essential Guide to Comprehensive Assessments! Sign up here

PowerShell PKI Module Documentation

Documentation Home
This command is not available in non-domain environments
This command requires installed Remote Server Administration Tools (RSAT)

Set-OnlineResponderRevocationConfiguration

Synopsis

Configures Online Responder revocation configuration specific settings.

Syntax

Set-OnlineResponderRevocationConfiguration -RevocationConfiguration <OcspResponderRevocationConfiguration[]> -SigningServer <CertificateAuthority> -SigningCertTemplate <String> [-HashAlgorithm <Oid2>] [-SigningFlag <OcspSigningFlags>] [-ReminderDuration <Int32>] [-BaseCrlUrl <String[]>] [-DeltaCrlUrl <String[]>] [-SerialNumbersDirectory <String[]>] [-CrlUrlTimeout <Int32>] [-RefreshTimeout <Int32>] [<CommonParameters>]

Set-OnlineResponderRevocationConfiguration -RevocationConfiguration <OcspResponderRevocationConfiguration[]> [-SigningCertificate <X509Certificate2>] [-HashAlgorithm <Oid2>] [-SigningFlag <OcspSigningFlags>] [-ReminderDuration <Int32>] [-BaseCrlUrl <String[]>] [-DeltaCrlUrl <String[]>] [-SerialNumbersDirectory <String[]>] [-CrlUrlTimeout <Int32>] [-RefreshTimeout <Int32>] [<CommonParameters>]

Description

Configures Online Responder revocation configuration specific settings. These settings are related only to specified revocation configuration and are replicated to all array members from array controller.

Typical revocation configuration settings are related to OCSP signing certificate enrollment and assignment approach. There are two OCSP signing certificate enrollment and assignment approaches:

1. Automatically enrolled and assigned OCSP signing certificate

This approach uses Microsoft Enterprise Certification Authority to automatically enroll and renew OCSP signing certificate. Microsoft Online Responder doesn't require the OCSP signing certificate to be signed by same CA server as was used to create revocation configuration. This approach is best suited for Microsoft Enterprise Certification Authorities and for other CA types (including non-Microsoft CAs) which doesn't require the OCSP signing certificate to be signed by same CA as was used to created revocation configuration. When this approach is used, the following conditions must be met:

— '-SigningServer' and '-SigningCertTemplate' parameters must be specified.
— '-SigningFlag' enumeration must include the following flags: 'SigningCertAutoRenewal, AutoDiscoverSigninCert, SigningCertAutoEnrollment'
— if '-SigningFlag' enumeration includes "ForceDelegatedCert" flag, then '-SigningServer' must match the CA used to create revocation configuration.

2. Manual (out-of-band) OCSP signing certificate enrollment and assignment.

This approach uses custom and out-of-band process to enroll for OCSP signing certificate and explicit OCSP signing certificate assignment. This approach is best suited for offline CAs and non-Microsoft Certification Authority implementations and when OCSP signing certificate must be issued by same CA as was used to create revocation configuration. When this approach is used, the following conditions must be met:

— '-SigningFlag' enumeration must include the following flags: 'ManualSigningCert'
— '-SigningFlag' enumeration exclude the following flags: 'SigningCertAutoRenewal, AutoDiscoverSigninCert, SigningCertAutoEnrollment'

Signing certificate is assigned by using '-SigningCertificate' parameter.

Note: this action shall be executed on array controller. Otherwise, these changes may be overwritten during array member synchronization with array controller.

Parameters

-SigningCertificate <X509Certificate2>

Specifies the signing certificate used to sign OCSP responses for current CA. Signing certificate must have an associated private key.

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

-SigningCertTemplate <String>

Specifies the certificate template common name Online Responder will use to enroll for signing certificate. When this parameter is specified, '-SigningCertTemplate' parameter is mandatory.

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

-HashAlgorithm <Oid2>

Specifies the hashing algorithm used to sign OCSP responses.

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

-ReminderDuration <Int32>

Specifies a percentage of the signing certificate validity period at which the responder will notify the administrator that certificate is about to expire. Default value is 90%.

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

-BaseCrlUrl <String[]>

Specifies an array of Base CRL URLs revocation configuration will use to fetch Base CRL. This CRL is used by Online Responder to determine the revocation status of requested certificate.

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

-SerialNumbersDirectory <String[]>

Specifies an array of UNC or local file paths that are being used by the Certification Authority to store the serial numbers of issued certificates.

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

-CrlUrlTimeout <Int32>

Specifies the time-out in seconds that the revocation provider must wait before it times out while trying to retrieve the CRL for which it is configured.

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

-RefreshTimeout <Int32>

Specifies the reference CRL cache lifetime in minutes. If the value is zero, then CRL cache is valid while CRLs are valid. Otherwise, reference CRLs are re-fetched at specified intervals.

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

-RevocationConfiguration <OcspResponderRevocationConfiguration[]>

Specifies the revocation configuration to modify. This object can be retrieved by calling Get-OnlineResponderRevocationConfiguration, or Add-OnlineResponderRevocationConfiguration commands.

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

-DeltaCrlUrl <String[]>

Specifies an array of Delta CRL URLs revocation configuration will use to fetch Delta CRL. This CRL is used by Online Responder to determine the revocation status of requested certificate. Do not use this parameter if referenced Certification Authority is not configured to publish Delta CRLs.

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

-SigningServer <CertificateAuthority>

Specifies the Enterprise Certification Authority used to enroll for OCSP signing certificate. When this parameter is specified, '-SigningServer' parameter is mandatory.

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

-SigningFlag <OcspSigningFlags>

Specifies the signing certificate used to sign OCSP responses for current CA. Signing certificate must have an associated private key.

Required? False
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

SysadminsLV.PKI.Management.CertificateServices.OcspResponderRevocationConfiguration

Outputs

SysadminsLV.PKI.Management.CertificateServices.OcspResponderRevocationConfiguration

Notes

Examples

Example 1

PS C:\> $OcspSigningCA = Get-CertificationAuthority "ca01.example.org"
Connect-OnlineResponder "ocsp1.example.com" | Get-OnlineResponderRevocationConfiguration -Name "Example Org v0.0" | Set-OnlineResponderRevocationConfiguration `
    -SigningCertTemplate "OcspResponseSigning" `
    -SigningServer $OcspSigningCA `
    -SigningFlag "Silent, SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigninCert, ResponderIdKeyHash, SigningCertAutoEnrollment" `
    -BaseCrlUrl "http://cdp2.example.com/exca.crl","http://cdp3.example.com/exca.crl" `
    -DeltaCrlUrl "http://cdp2.example.com/exca+.crl","http://cdp3.example.com/exca+.crl" `
    -HashAlgorithm (New-Object SysadminsLV.PKI.Cryptography.Oid2 "sha256", $false)

This example configures revocation configuration named "Example Org v0.0" to: a) use "OcspResponseSigning" certificate template to enroll for OCSP signing certificate, b) automatic signing certificate renewal, Online Responder identification by CA public key hash c) URLs that point to reference Base and Delta CRLs d) use SHA256 hashing algorithm to hash and sign OCSP responses.

Example 2

PS C:\> Connect-OnlineResponder "ocsp1.example.com" | Get-OnlineResponderRevocationConfiguration -Name "External Example Org CA" | Set-OnlineResponderRevocationConfiguration `
    -SigningFlag "Silent, ManualSigningCert, AllowNonce" `
    -BaseCrlUrl "http://cdp2.example.com/exca.crl","http://cdp3.example.com/exca.crl" `
    -HashAlgorithm (New-Object SysadminsLV.PKI.Cryptography.Oid2 "sha256")

This example configures revocation configuration to: a) use out-of-band enrolled OCSP signing certificate b) allow Nonce in OCSP requests c) base CRL URLs (assuming Delta CRLs are not used by CA) d) SHA256 hashing algorithm used to sign OCSP responses.

Related links

Connect-OnlineResponder
Set-OnlineResponderProperty

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