PowerShell PKI Module Documentation

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>] [[-SigningCertificate] <X509Certificate2>] [[-SigningCertTemplate] <String>] [[-HashAlgorithm] <Oid2>] [[-SigningFlag] <OcspSigningFlag>] [[-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? 2
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? False
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? True

-HashAlgorithm <Oid2>

Specifies the hashing algorithm used to sign OCSP responses.

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

-SigningFlag <OcspSigningFlag>

Specifies the signing certificate handling options. See OcspSigningFlag Enumeration for possible values and their meaning. The following flags or flags combination can be used:

Silent – do not raise UI prompt when OCSP signing private key is accessed. Do not assert this flag when signing private key is stored on a hardware device (such as HSM).
UseCaCert – uses CA certificate and private key to sign OCSP responses. This flag shall not be used for security reasons.
SigningCertAutoRenewal – automatically renews OCSP signing certificate.
ForceDelegatedCert – requires the OCSP signing certificate to be signed by same CA as specified in revocation configuration.
AutoDiscoverSigningCert – automatically locates the most suitable OCSP signing certificate when multiple OCSP signing certificates are installed.
ManualSigningCert – OCSP signing certificate is assigned manually. Cannot be used with SigningCertAutoRenewal, AutoDiscoverSigningCert.
ResponderIdKeyHash – Online Responder is identified by CA public key hash in OCSP responses. Cannot be used with ResponderIdCertName.
ResponderIdCertName – Online Responder is identified by CA Subject name in OCSP responses. Cannot be used with ResponderIdKeyHash.
AllowNonce – allows nonce requests from client.
SigningCertAutoEnrollment – automatically enrolls OCSP signing certificate.

When Online Responder revocation configuration is created from Enterprise Certification Authority and supposed to use automatic OCSP signing certificate enrollment and renewal from Enterprise CA, the following default flags are used: "Silent, SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigninCert, ResponderIdKeyHash, SigningCertAutoEnrollment".

When Online Responder revocation configuration uses out-of-band OCSP signing certificate enrollment, renewal, management and manual assignment, the following default flgs are used: "Silent, ManualSigningCert, ForceDelegatedCert, AutoDiscoverSigninCert, ResponderIdKeyHash, SigningCertAutoEnrollment"

Required? False
Position? 5
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? 6
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? 7
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? 9
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? 10
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? 11
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? 0
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? 8
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? False
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

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 System.Security.Cryptography.Oid2 "sha256")

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 System.Security.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

  • PowerShell 3.0

Operating System Support

  • Windows 7
  • Windows 8
  • Windows 8.1
  • Windows 10
  • 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