Intro
Every single Microsoft Online Responder is capable to provide certificate status for multiple different certification authorities. When OCSP client perform request, it includes CA identification in CertID structure:
CertID ::= SEQUENCE {
hashAlgorithm AlgorithmIdentifier,
issuerNameHash OCTET STRING, -- Hash of issuer's DN
issuerKeyHash OCTET STRING, -- Hash of issuer's public key
serialNumber CertificateSerialNumber }
issuerNameHash and issuerKeyHash fields (selected in bold) allow the OCSP server to distinguish requested CA and exact key, if there are multiple keys for given CA. Microsoft Online Responder implements this support using revocation configuration concept. Within each revocation configuration you specify (at a minimum) CA certificate and a set of URLs to issuer revocation lists. Let’s take a look at some practical examples.
Reading revocation configurations
As it was mentioned in the first post, all Online Responder specific management stuff is started with Connect-OnlineResponder. It is reasonable to save this object into variable for future reference. Then use Get-OnlineResponderRevocationConfiguration command to read revocation configurations:
PS C:\> $ocsp = Connect-OnlineResponder hq-s-adcsws1
PS C:\> $ocsp | Get-OnlineResponderRevocationConfiguration
ComputerName Name Status
------------ ---- ------
hq-s-adcsws1.sysadmins.lv Sysadmins LV Class 1 Extended Validation CA-2 (v0.0) 0
hq-s-adcsws1.sysadmins.lv Sysadmins LV Internal Class 1 SubCA-1 (v0.0) -2147023288
hq-s-adcsws1.sysadmins.lv Sysadmins LV Internal Class 1 SubCA-1 (v1.1) 0
PS C:\> $ocsp | Get-OnlineResponderRevocationConfiguration -Name "Sysadmins LV Internal Class 1 SubCA-1 (v1.1)"
ComputerName Name Status
------------ ---- ------
hq-s-adcsws1.sysadmins.lv Sysadmins LV Internal Class 1 SubCA-1 (v1.1) 0
PS C:\>
Without parameters, Get-OnlineResponderRevocationConfiguration returns all revocation configurations. Use -Name parameter to retrieve revocation configuration by its name. We see basic information about each configuration: OCSP server that hosts the configuration, configuration name and its status as Win32 HRESULT. You can use Get-ErrorMessage to convert status code to textual meaning. Now, dig deeper into revocation configuration properties:
PS C:\> $ocsp | Get-OnlineResponderRevocationConfiguration -Name "Sysadmins LV Internal Class 1 SubCA-1 (v1.1)" | fl *
ComputerName : hq-s-adcsws1.sysadmins.lv
Name : Sysadmins LV Internal Class 1 SubCA-1 (v1.1)
ConfigString :
CACertificate : [Subject]
CN=Sysadmins LV Internal Class 1 SubCA-1, OU=Information Systems, O=Sysadmins LV, C=
LV
[Issuer]
CN=Sysadmins LV Class 1 Root Certification Authority, OU=Information Systems, O=Sysa
dmins LV, C=LV
<...>
SigningCertificate : [Subject]
CN=hq-s-adcsws1.sysadmins.lv
[Issuer]
CN=Sysadmins LV Internal Class 1 SubCA-1, OU=Information Systems, O=Sysadmins LV, C=
LV
<...>
SigningCertificateTemplate : OCSPResponseSigning
HashAlgorithm : System.Security.Cryptography.Oid2
CryptoProviderName : Microsoft Software Key Storage Provider
SigningFlags : Silent, SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigningCert, Responder
IdKeyHash, SigningCertAutoEnrollment
ReminderDuration : 90
LocalRevocationInformation : {}
BaseCrlUrls : {http://cdp.sysadmins.lv/repository/pica-1(1).crl}
DeltaCrlUrls : {http://cdp.sysadmins.lv/repository/pica-1(1)+.crl}
CrlUrlTimeout : 0
RefreshTimeout : 10
IssuedSerialNumbersDirectories :
RevocationStatusCode : 0
ConfigurationStatusCode : 0
PS C:\>
We see wide range of configuration-specific properties. We see CA certificate associated with the current configuration, signing certificate, certificate template (in case if signing certificate is autoenrolled from Enterprise CA), base and delta CRL URLs and other properties. You can find meaning of each property on OcspResponderRevocationConfiguration Class documentation page.
In initial version, there was bug in SigningCertificateTemplate property, so it doesn’t return value. It is already fixed in v3.7.2+.
Removing existing revocation configuration
All actions showed in this and subsequent must be executed on array controller unless specified otherwise.
You can remove unused revocation configuration using Remove-OnlineResponderRevocationConfiguration command. As command syntax show, we have two options to remove the configuration: by piping revocation configuration object, or piping online responder object and passing revocation configuration name. Examples are easy and clear enough and I will skip them here.
Adding new revocation configuration
Using Add-OnlineResponderRevocationConfiguration command we can create new revocation configuration. This process requires some initial planning, because there are several revocation configuration strategies. These strategies are implemented in OCSP revocation configuration creation wizard in MMC snap-in. Here is a summary of possible strategies:
- Enterprise CA. Signing certificate is enrolled and renewed automatically using certificate template issued by same CA;
- Arbitrary CA. Signing certificate is enrolled and renewed automatically using certificate template issued by another delegated CA. This scenario is supported by RFC 5019;
- Arbitrary CA. Signing certificate is enrolled, renewed and assigned manually, using out-of-band process.
In PSPKI, we support all of them, but split in two:
- Enterprise CA. Signing certificate is enrolled and renewed automatically using certificate template issued by same or another delegated CA;
- Everything else.
We have two parameter sets within Add-OnlineResponderRevocationConfiguration command:
- Using
-CertificationAuthority parameter, when you intend to create a new revocation configuration for Enterprise CA. Referenced CA will be configured to issue OCSP signing certificate for this configuration.
- Using
-CaCertificate parameter, in all other scenarios. Whether OCSP signing certificate will be automatically enrolled and renewed by another delegated Enterprise CA, or manual out-of-band OCSP signing certificate enrollment process.
There are no other interesting parameters apart from -Name which is mandatory in all cases and specifies a friendly name of revocation configuration. There are no other parameters to configure revocation configuration. We save only minimal configuration and then use Set-OnlineResponderRevocationConfiguration command which is used to configure any revocation configuration. The documentation covers most common scenarios.
Configuring revocation configuration
After creating new configuration, it must be configured as per your needs. Or you may wish to update existing revocation configuration. It is done using Set-OnlineResponderRevocationConfiguration. This command has many configurable options, most of which are available in Online Responder Management MMC snap-in only when you create revocation configuration. Once created, it provides very limited configurable options. With PSPKI, these options are unlocked even for existing configurations.
Some configuration options are familiar to admins who created revocation configurations using Online Responder Management MMC snap-in. For example, -BaseCrlUrl, -DeltaCrlUrl, -HashAlgorithm, -RefreshTimeout. We tried to make the cmdlet documentation as clean and complete as possible, so I will focus on some concepts and dependencies only.
Several aspects of revocation configuration behavior are defined in -SigningFlag parameter which is an enumeration of OcspSigningFlag type. This adds flexibility and some complexity, because flags inside enumeration can be mutually exclusive. For example, ResponderIdKeyHash and ResponderIdCertName are mutually exclusive. It is recommended to keep only ResponderIdKeyHash flag enabled between these two.
Another mutually exclusive flag pair is ManualSigningCert and SigningCertAutoRenewal. As per strategies explained above, first flag is used when OCSP signing certificate is enrolled using out-of-band process and then manually assigned.
UseCaCert flag is only acceptable when OCSP is installed on CA server itself, which isn’t a good practice, so it is unlikely that you will ever use this flag.
SigningCertAutoEnrollment flag requires that ConfigString and SigningCertificateTemplate are not null or empty, because these properties contain information about OCSP signing certificate enrollment. If they are empty and you want to enable automatic OCSP signing certificate enrollment, use -SigningServer and -SigningCertTemplate parameters to supply this information.
Silent flag MUST NOT be enabled when OCSP signing key is stored on HSM. In all other cases, it shall be asserted.
ForceDelegatedCert flag requires the OCSP signing certificate to be signed by same CA as specified in CACertificate property. If another CA is signing OCSP signing certificate, this flag must be removed.
If you want to add or remove particular flag, you need to re-enter the full string of desired flags. For example, you have the following combination: “Silent, SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigninCert, ResponderIdKeyHash, SigningCertAutoEnrollment” and you want to enable AllowNonce, flag, then you have to append this flag to source flags string and pass entire string to SigningFlag parameter, e.g. “Silent, SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigninCert, ResponderIdKeyHash, SigningCertAutoEnrollment, AllowNonce”. Or pass a numerical equivalent of enabled flags. Common numerical values are:
- 605 – when OCSP signing certificate is automatically enrolled and renewed from any existing Enterprise CA
- 97 – when OCSP signing certificate is obtained and assigned manually.
In order to manually assign the OCSP signing certificate, it must be installed in LocalMachine\My store and Network Service account must have Read permissions on private key. Then use PowerShell certificate provider to retrieve the certificate object from store and pass certificate object to -SigningCertificate parameter.
Managing local revocation information
Microsoft OCSP server implementation uses CA-issued CRLs to get revocation status for requested serial number. In addition, you can maintain a custom list of revoked certificates. Both CRLs are cumulative, that is, an effective list of revoked certificates is a superset of local CRL and CA-issued CRL. This is handy in following scenarios:
- Certificate is revoked, but not yet available in referenced CRL. You can manually add revoked certificate’s serial number to local CRL.
- a disaster occurred and you can’t sign new up to date CRL. You can copy revocation list to local CRL and keep OCSP server to respond with valid responses.
Local CRL mimics real CRL with validity matching the CA certificate validity. It is not signed, so you don’t need to have a CA private key to sign it.
Expiration date for OCSP response that is based on referenced CRL validity. So if OCSP uses local CRL to lookup for certificate status, response will be valid for a quite long time, until CA certificate expires, therefore use local CRL information carefully.
We have two cmdlets to manage local CRL: Add-OnlineResponderLocalCrlEntry and Remove-OnlineResponderLocalCrlEntry. As input parameter, they both accept revocation configuration objects.
You can add new entries in two ways: by manually passing a list of serial numbers, pass a collection of CRL entries. Later option is suitable when you want to copy entire revocation list from existing CRL. Optionally, you can provide revocation reason if necessary. Switch -Force specifies whether existing local CRL is overwritten or not. If specified and is set to $true, then existing local CRL is reset and new entries added, otherwise, new entries are appended to existing CRL.
In similar way, you can remove entries from local CRL using Remove-OnlineResponderLocalCrlEntry. Removal is supported in two ways: by removing individual serial numbers or completely clear local CRL.
PS C:\> Connect-OnlineResponder hq-s-adcsws1 | Get-OnlineResponderRevocationConfiguration -Name "Sysadmins LV Internal Class 1 SubCA-1 (v1.1)" | Add-OnlineResponderLocalCrlEntry -SerialNumber "7114FA7EA06D3F33EDDEE713EBDEE3AD020E66CC" | fl *
ComputerName : hq-s-adcsws1.sysadmins.lv
Name : Sysadmins LV Internal Class 1 SubCA-1 (v1.1)
ConfigString : hq-s-ipica1.sysadmins.lv\Sysadmins LV Internal Class 1 SubCA-1
CACertificate : [Subject]
<...>
SigningCertificate : [Subject]
<...>
SigningCertificateTemplate : OCSPResponseSigning
HashAlgorithm : System.Security.Cryptography.Oid2
CryptoProviderName : Microsoft Software Key Storage Provider
SigningFlags : SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigningCert, ResponderIdKeyHas
h, SigningCertAutoEnrollment
ReminderDuration : 90
LocalRevocationInformation : {Serial number: 7114fa7ea06d3f33eddee713ebdee3ad020e66cc revoked at: 14.08.2020 11:03:
56}
BaseCrlUrls : {http://cdp.sysadmins.lv/repository/pica-1(1).crl}
DeltaCrlUrls : {http://cdp.sysadmins.lv/repository/pica-1(1)+.crl}
CrlUrlTimeout : 0
RefreshTimeout : 10
IssuedSerialNumbersDirectories :
RevocationStatusCode : 0
ConfigurationStatusCode : 0
PS C:\> Connect-OnlineResponder hq-s-adcsws1 | Get-OnlineResponderRevocationConfiguration -Name "Sysadmins LV Internal Class 1 SubCA-1 (v1.1)" | Remove-OnlineResponderLocalCrlEntry -Force | fl *
ComputerName : hq-s-adcsws1.sysadmins.lv
Name : Sysadmins LV Internal Class 1 SubCA-1 (v1.1)
ConfigString : hq-s-ipica1.sysadmins.lv\Sysadmins LV Internal Class 1 SubCA-1
CACertificate : [Subject]
<...>
SigningCertificate : [Subject]
<...>
SigningCertificateTemplate : OCSPResponseSigning
HashAlgorithm : System.Security.Cryptography.Oid2
CryptoProviderName : Microsoft Software Key Storage Provider
SigningFlags : SigningCertAutoRenewal, ForceDelegatedCert, AutoDiscoverSigningCert, ResponderIdKeyHas
h, SigningCertAutoEnrollment
ReminderDuration : 90
LocalRevocationInformation : {}
BaseCrlUrls : {http://cdp.sysadmins.lv/repository/pica-1(1).crl}
DeltaCrlUrls : {http://cdp.sysadmins.lv/repository/pica-1(1)+.crl}
CrlUrlTimeout : 0
RefreshTimeout : 10
IssuedSerialNumbersDirectories :
RevocationStatusCode : 0
ConfigurationStatusCode : 0
PS C:\>
This is all what I wanted to discuss on OCSP revocation configuration options in PowerShell PKI module. Again, don’t forget to read every cmdlet documentation. We tried to make them clear enough. Next time, I will write about changes in ADCS object ACL management. Stay tuned!
Schedule a Demo
