OCSP responder section

This article includes updates for Nexus OCSP Responder 6.3.0.

This article describes how to specify the OCSP responders that shall handle the incoming OCSP requests (these OCSP responders are referred to as 'the logical OCSP responders', for more information, see Nexus OCSP Responder architecture overview). The specification is done in the "OCSP responder" section of the Nexus OCSP Responder configuration file. There are predefined OCSP responders with different semantics. Use the type parameter to specify which one to use. The workflows for different types of OCSP responders are described in Workflow for Nexus OCSP Responders.

A responder may also forward the request to a remote OCSP responder.
Each responder can support multiple CAs.
Configure a signer for each CA that the responder should support.
In the responders, configure each CA that shall be supported.

The responder replies with status 'Unknown' to OCSP requests for certificates issued by CAs that the responder is not responsible for. When receiving requests related to CAs that are not supported, the first configured signer is used to sign the response. This means that a default "dummy" signing certificate can be configured as the first supported issuer/signer for responding to irrelevant or malicious requests.

Specify the OCSP responders

It is mandatory to specify at least one responder and set the following parameters:

...type
...url
...workers
...signer.x.issuerdn
...signer.x.dn
...signer.x.pin

Authentication, authorization and billing are disabled by default.

For each OCSP responder, specify as follows in the OCSP configuration file:

CODE

responder.<r#>.type=[basic|cached|identrus-basic|identrus-cached|non-issued-basic|non-issued-cached|fallback]
responder.<r#>.url=[http|https]://<host>[:<port>][/<path>]

; ssl node
responder.<r#>.ssl.clientauth=[true|false]
responder.<r#>.ssl.certificate=<certificate pattern>
responder.<r#>.ssl.pin=<PIN>
responder.<r#>.ssl.cipher=<cipher suites>
responder.<r#>.ssl.protocol=<protocols>

responder.<r#>.workers=<# of workers>
responder.<r#>.connections=<# of connections>
responder.<r#>.socketreadtimeout=<socket read timeout>
responder.<r#>.forwarding.enabled=[true|false]

; signer node
responder.<r#>.signer.<s#>.issuerdn=<distinguished name>
responder.<r#>.signer.<s#>.certificate=<certificate pattern>
responder.<r#>.signer.<s#>.signingalgorithm=<algorithmname>
responder.<r#>.signer.<s#>.pin=<PIN>
responder.<r#>.signer.<s#>.setnextupdate=[true|false]

; fallback node
responder.<r#>.fallback.certificate=<certificate pattern>
responder.<r#>.fallback.pin=<PIN>
responder.<r#>.fallback.truststore=<folder path>
responder.<r#>.fallback.url=<url>
responder.<r#>.fallback.checkonhold=[true|false]

responder.<r#>.archivecutoff=[true|false]

See this table for description of constants and values:

Configuration	Description	Type description	Example
`type=<type>`	Defines the type of responder, the following responder types are available : Enter `basic` to include capabilities for authentication, authorization and billing. These capabilities are included in all of the following. Enter `cached` to add capabilities to those of basic for checking of the response cache. Enter `identrus-basic` to add capabilities to those of basic for no `nextUpdate` in OCSP responses. Enter `identruscached` to add capabilities to those of basic for checking of the response cache, freshness proof and no `nextUpdate` in OCSP responses. Enter `non-issued-basic` to include capabilities for authentication, authorization (extended), validation of non-issued certificates (see Certificate Issuance List - CIL). Enter `non-issued-cached` to add capabilities to those of non-issued-basic for checking of the response cache. Enter `fallback` to activate CF-fallback functionality for requesting the real-time certificate status from CF.	The responder Type, : `<type>` choose one (mandatory): `basic` `cached` `identrus-basic` `identruscached` `non-issued-basic` `non-issuedcached` `fallback`	`responder.1.type = basic`
`url=<url>`	Listening address of the responder	`<url>` should follow the format: `[http\|https]://<host>:<port>/<path>` `<host>`: listening host, Use `` if the responder should listen on all interfaces. `:<port>` : specify the port Default: `:80` for HTTP `:443` for HTTPS `/<path>`: specify the path Default*: empty	`responder.1.url=http://*:8080/fallback`
`ssl.clientauth=[true\|false]` `ssl.certificate=<certificate pattern>` `ssl.pin=<PIN>` `ssl.cipher=<cipher suites>` `ssl.protocol=<protocols>`	SSL configuration for the responder (https only). `ssl.clientauth` : defines if client authentication is required Default: `false` `ssl.certificate`: specifies the server certificate to use from the key store. See Key management section `ssl.pin`: specifies the pin used to access the specified server certificate and private key. See Key management section `ssl.cipher`: TLS cipher suites that should be enabled. Default: all supported cipher suites of Java's SunJSSE (Java Secure Socket Extension (JSSE) Reference Guide for JDK 11) `ssl.protocol`: TLS protocols that should be enabled Default: all supported protocols of Java's SunJSSE (Java Secure Socket Extension (JSSE) Reference Guide for JDK 11)	`<cipher suites>`: A comma separated list of TLS cipher suites that should be enabled. `<protocols>`: A comma separated list of TLS protocols that should be enabled.	`responder.1.ssl.clientauth=true` `responder.1.ssl.certificate=CN=nexus-tls-certificate` `responder.1.ssl.pin=1234` `responder.1.ssl.cipher=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384` `responder.1.ssl.protocol=TLSv1.2,TLSv1.3`
`workers=<integer>`	The number of requests that can be handled simultaneously. The optimal value depends on the number of processors, processing power and memory. Default: `10`		`responder.1.workers=16`
`signer.<s#>.issuerdn=<distinguished name>` `signer.<s#>.certificate=<certificate pattern>` `signer.<s#>.signingalgorithm=<algorithmname>` `signer.<s#>.pin=<PIN>` `signer.<s#>.setnextupdate=[true\|false]`	Configuration for the responder’s signer. Multiple signers can be defined per responder by simply incrementing the signer index: `#s`. For more information and examples see: key-management-section. `<setnextupdate>`: defines if NextUpdate attribute should be included in the signer’s response		`responder.1.signer.1.issuerdn=cn=Root CA,c=SE` `responder.1.signer.1.certificate=cn=OCSP-signer*` `responder.1.signer.1.signingalgorithm=SHA256withRSA` `responder.1.signer.1.pin=1234`
`expiryCheck.disable=true\|false` `expiryCheck.period=<time expr>` `expiryCheck.warningBefore=<time expr>` `expiryCheck.severeBefore=<time expr>`	Expiry Check is a service that sends reminder logs when a responder' signer certificate is about to expire. For more information on how to configure this service check out the OCSP expiry Check page.		`responder.1.expiryCheck.disable=false` `responder.1.expiryCheck.period=P24H` `responder.1.expiryCheck.warningBefore=P30D` `responder.1.expiryCheck.severeBefore=P5D`
`connections=<integer>`	The number of requests that can be handled simultaneously. The optimal value depends on the number of processors, processing power and memory. Default: 2000		`responder.1.connections=10`
`socketreadtimeout=<time expr>`	`socketreadtimeout` After a socket has been opened to the server, the server will wait for this amount of time until it will automatically close the socket if no request has been received. Default: `PT1M` (one minute)	`<time expr>` should follow iso-8601 duration format.	`responder.1.socketreadtimeout=PT1M`
`forwarding.enabled=[true\|false]`	This parameter defines if forwarding should be enabled. Read more in "Specify forwarding of requests" below. Default: `false`		`responder.1.forwarding.enabled=false`
`archivecutoff=[true\|false]`	Defines if the `ArchiveCutoff` extension is included in the responder’s response. This extension will utilize the value from the `ExpiredCertsInCrl` extension in the Certificate Revocation List (CRL) and will only be added if the corresponding extension is present. Default: `false`		`archivecutoff=true`
`fallback.certificate=<certificate pattern>` `fallback.pin=<PIN>` `fallback.truststore=<folder path>` `fallback.url=<url>` `fallback.checkonhold=[true\|false]`	This configuration node is specific to the `fallback` responder type. For more information about this responder's configuration see: fallback responder page.		`fallback.certificate=CN=cf-fallback-officer-1` `fallback.pin=1234` `fallback.truststore=fallback-truststore/` `fallback.url=https://pgwy:8444/pgwy/api/certificates` `fallback.checkonhold=true`

Specify limitations on incoming requests

To read more regarding access control, see Access control and billing.

Specify limitations on the incoming requests to the OCSP responder as follows:

CODE

responder.<r#>.incoming.signature.required=[true|false]
responder.<r#>.incoming.authorization=[none|bynamematch|byauthentication]

If you enter bynamematch you also have to specify a table of rules to find a match of the distinguished name as follows:
CODE
```
responder.<r#>.incoming.authorization.match.<n#>=<distinguished name>
```
See also Distinguished name matching and Access control and billing.
In addition, you can also use a certificate pattern to filter allowed client requests, specify as follows:
CODE
```
responder.<r#>.incoming.filter.<n#>=<certificate pattern>
```
See this table for description of constants and values:

Constants and Values	Description
`<r#>`	Replace `<r#>` with the responder sequence number.
`true \| false` for parameter `...signature.required`	Enter `true` to require, `false` not to require the request to be signed. If you intend to perform billing and SSL is not used, enter true. Default: `false`
`none \| bynamematch \| byauthentication`	This configures authorization of the client certificate. If the request is signed, that certificate will be verified during authorization. Otherwise the client certificate used in the TLS handshake will be verified. Enter `none` to indicate that no authorization check shall be performed. Enter `bynamematch` to indicate a search for a match in the specified table. This setting is effective only if either of the parameters `...ssl.clientauth` or `...signature.required` is set to true. Enter `byauthentication` to look for the certificate in the OCSP responders trust store. Default: `none`
`<n#>`	Replace `<n#>` with the name sequence number.
`<distinguished name>`	Replace `<distinguished name>` with the rule to match the distinguished name. Wildcards are allowed.
`<certificate pattern>`	A certificate pattern as described in Introduction to LDAP. Filters authenticated certificates on certificate attributes (part of the authorization scheme). Default is not to filter, which allows any authenticated certificate to bypass the filter mechanism.

Specify responder and responses

In the OCSP configuration file, specify as follows:

CODE

responder.<r#>.signature.enforceocspsign=[true|false]
responder.<r#>.signature.othercerts=[none|byname|bykey]
responder.<r#>.signature.chain=[none|cert|chain|allchains]
responder.<r#>.signature.chain.includeroot=[true|false]
responder.<r#>.responderid=[byname|bykey|byski]
responder.acceptPlusSignInRequests=[true|false]
responder.endSpaceInHttpStatusLine=[true|false]

See this table for description of constants and values:

Constants and Values	Description
`<r#>`	Replace `<r#>` with the responder sequence number.
`true \| false` for parameter `...enforceocspsign`	Enter `true` to check, `false` not to check that "OCSP signing" is set in the extension `ExtendedKeyUsage` of the signature certificate(s). Default: `true` If this parameter is set to `true` and `ExtendedKeyUsage` does not contain "OCSP signing", Nexus OCSP Responder will write a message to the log file and stop executing.
`none \| byname \| bykey` for parameter `...othercerts`	Enter `none` to indicate that the response shall include only the signature certificate. Enter `byname` to let Nexus OCSP Responder search the certificate cache for other certificates with the same public key as the signature certificate, but only include those in the response, which also have the same subject distinguished name. Enter `bykey` to let Nexus OCSP Responder search the certificate cache for other certificates with the same public key as the signature certificate and include them in the response. Default: none The parameter `...othercerts` will be ignored if the parameter `...chain` is set to `none`.
`none \| cert \| chain \| allchains`	Enter `none` to indicate that no signature certificate(s) shall be appended to the response. Enter `cert` to indicate that the signature certificate shall be appended to the response. If parameter `...othercerts` is set to "`byname`" or "`bykey`", all applicable certificates shall be appended. Enter `chain` to indicate that one chain of certificates, chaining to the trust store, shall be appended to the response. If parameter `...othercerts` is set to "`byname`" or "`bykey`", one chain for every applicable certificate shall be appended. Enter `allchains` to indicate that all possible certificate chains shall be appended to the response. If parameter `...othercerts` is set to "`byname`" or "`bykey`", all valid chains for all applicable certificates shall be appended. Default: `chain`
`true \| false` for parameter `...includeroot`	Enter `true` to include, `false` not to include the root certificate in the chains. Default: `true` This parameter is relevant only when `...signature.chain` is set to `chain` or `allchains`.
`byname \| bykey \| byski` for parameter `...responderid`	Enter `byname` to identify the responder by its distinguished name in the response. Enter `bykey` to identify the responder by the hash value of its public key. Enter `byski` to identify the responder by the value from the X.509 extension "Subject Key Identifier". Default: `byname`
`true \| false` for parameter `...acceptPlusSignInRequests`	Set this parameter to `true` to make OCSP accept plus signs in incoming requests. Default: `false`
`true \| false` for parameter `...endSpaceInHttpStatusLine`	Use this parameter to align HTTP responses with RFC9112 by adding a space after the status code, even if there isn't a reason-phrase. If set to `true` then the status line will be in the following form: statusline = HTTP-version SP status-code SP [ reason-phrase ] Default: `false`

Specify billing information

Billing is described in Access control and billing.

In the OCSP configuration file, specify as follows:

CODE

responder.<r#>.billing.enabled=[true|false]
responder.<r#>.billing.perrequest=[true|false]
responder.<r#>.billing.percert=[true|false]
responder.<r#>.billing.countunknown=[true|false]
responder.<r#>.billing.includestatus=[true|false]

See this table for description of constants and values:

Constants and Values	Description
`<r#>`	Replace `<r#>` with the responder sequence number.
`true \| false` for parameter `...billing.enabled`	Enter `true` to enable, `false` not to enable billing. Default: `false`
`true \| false` for parameter `...billing.perrequest`	Enter `true` to count, `false` not to count each request for revocation information the original client request will cause. Default: `true`
`true \| false` for parameter `...billing.percert`	Enter `true` to count, `false` not to count each requested certificate. Default: `true`
`true \| false` for parameter `...billing.countunknown`	Enter `true` to include, or `false` to not include responses with the status "unknown" in logging for `percert`. Default: `false`
`true \| false` for parameter `...billing.includestatus`	Enter `true` to include, or `false` to not include certificate status in logging for `percert`. Default: `false`

Specify forwarding of requests

Forwarding of requests is carried out by the back end OCSP client, which by default will use the settings you made in Back end client section, section"Specify OCSP client request". To override any of these settings, add a new specification here.

Use the same syntax as described for the back end client but replace ocsp.client with responder.<r#>.forwarding.client, where <r#> is the responder sequence number.

Example:

In this example, forwarding is enabled for queries related to certificates issued by the My CA authority.

CODE

responder.2.type=basic
responder.2.forwarding.enabled=true
responder.2.forwarding.client.response.allowunknown = true
responder.2.forwarding.onlyforissuer.1=cn=My CA,o=ACME Inc,c=SE
responder.2.forwarding.responseWhenInvalidResponseFromBackEndClient=internalerror

These three settings are also available:

This setting allows the back end client to modify the request before it is sent to another responder. OCSP forwarding really means "send the message, as it is, to another responder".
Default: false
CODE
```
responder.<r#>.forwarding.modify-request=[true|false]
```
This setting defines a match table for what issuers that OCSP forwarding should be enabled for. <issuermatch> is matched against the issuer DN. Wildcards are allowed.
CODE
```
responder.<r#>.forwarding.onlyforissuer.<n#>=<issuermatch>
```
If the back end client receives a valid response, this response is sent to the requesting client and the validation is finished. The parameter responseWhenInvalidResponseFromBackEndClient controls what Nexus OCSP Responder will do if the back end client failed to retrieve a valid response.
- Enter unknown to have Nexus OCSP Responder not respond, but rather continue with other modules, such as CRL/CIL checks. This will most likely result in an "unknown" response to the client. Note that this will cause Nexus OCSP Responder to sign the response using the default signer for that responder.
- Enter trylater to have Nexus OCSP Responder pass back "Try later" in the OCSP response.
- Enter internalerror to have Nexus OCSP Responder pass back "Internal error" in the OCSP response.
  Default: trylater
  CODE
```
responder.<r#>.forwarding.responseWhenInvalidResponseFromBackEndClient=[unknown|trylater|internalerror]
```

Specify freshness proof

For a description of the freshness proof functionality, see Freshness proof.

In the OCSP configuration file, specify as follows for type=identrus-cached:
CODE
```
responder.<r#>.freshnessproof.add=[true|false]
```
See this table for description of constants and values:

Constants and Values

Description

<r#>

Replace <r#> with the responder sequence number.

true | false

Enter true to add, false not to not add freshness proof.

Default: false

Specify system control

You can configure Nexus OCSP Responder to automatically shut down if an internal error occurs (when the sent OCSP response has internal error status).

In the OCSP configuration file, specify as follows:

CODE

responder.numberOfConsecutiveInternalErrorsBeforeShutdown=<n#>

Replace <n#> with the number of consecutive internal error responses to return before shutting the system down. A value below 1 disables the functionality.
Default value: -1.

Specify ping data

In the OCSP configuration file, specify ping data as follows:
CODE
```
responder.pingdata=<data>
```
Replace <data> with a string. When an incoming HTTP POST message contains this data in its body, Nexus OCSP Responder will respond with a simple HTTP 200 OK message and no logs will be produced. This can typically be used by a load balancer to frequently check that the server is up without producing excessive log files in Nexus OCSP Responder.

Examples

View examples

Nexus OCSP responder configuration

In the following examples, different responders are configured. Note that these examples are not complete configurations of the Nexus OCSP Responder.

CODE

; OCSP Responder configuration
; This responder supports Basic OCSP CA
responder.1.type=basic
responder.1.url=http://*:8080/1
responder.1.workers=5
responder.1.connections=2000
responder.1.signature.chain=cert
responder.1.signer.1.issuerdn=c=SE,cn=Basic OCSP CA
responder.1.signer.1.certificate=c=SE,cn=Basic OCSP Signer
responder.1.signer.1.pin=1234
responder.1.billing.enabled=true
responder.1.billing.percert=true
responder.1.billing.perrequest=true
responder.1.billing.countunknown=true
responder.1.billing.includestatus=true

; This responder supports Test CA A, B and C
; Signing algorithm set to SHA256withRSA
responder.2.type=basic
responder.2.url=http://*:8080/2
responder.2.workers=5
responder.2.connections=2000
responder.2.signature.chain=cert
responder.2.signer.1.issuerdn=c=SE,o=Nexus,cn=Test CA A
responder.2.signer.1.certificate=c=SE,O=Nexus,cn=Test CA A Signer
responder.2.signer.1.signingalgorithm=SHA256withRSA
responder.2.signer.1.pin=1234
responder.2.signer.2.issuerdn=c=SE,o=Nexus,cn=Test CA B
responder.2.signer.2.certificate=c=SE,O=Nexus,cn=Test CA B Signer
responder.2.signer.2.signingalgorithm=SHA256withRSA
responder.2.signer.2.pin=1234
responder.2.signer.3.issuerdn=c=SE,o=Nexus,cn=Test CA C
responder.2.signer.3.certificate=c=SE,O=Nexus,cn=Test CA C Signer
responder.2.signer.3.signingalgorithm=SHA256withECDSA
responder.2.signer.3.pin=1234
responder.2.signer.4.issuerdn=c=SE,o=Nexus,cn=Test CA D
responder.2.signer.4.certificate=c=SE,O=Nexus,cn=Test CA D Signer
responder.2.signer.4.signingalgorithm=Ed25519
responder.2.signer.4.pin=1234


; Specify the PKCS#12 key stores for the different signing certificates.
key.store.store.1=basic-ca-signer.p12
key.store.store.1.pin=secretPIN1234
key.store.store.2=generic-integration-test-ca-a-signer.p12
key.store.store.2.pin=secretPIN1234
key.store.store.3=generic-integration-test-ca-b-signer.p12
key.store.store.3.pin=secretPIN1234
key.store.store.4=generic-integration-test-ca-c-signer.p12
key.store.store.4.pin=secretPIN1234
key.store.store.5=generic-integration-test-ca-d-signer.p12
key.store.store.5.pin=secretPIN1234

Nexus OCSP responder proxy configuration

Use this sample configuration to set up Nexus OCSP Responder to forward all incoming OCSP requests to another (OCSP) responder:

Example 1

CODE

; This responder supports all CAs and forwards to another responder
responder.1.type=basic
responder.1.url=http://*:8080/1
responder.1.workers=5
responder.1.connections=2000
responder.1.signature.chain=cert
responder.1.signer.1.issuerdn=c=SE,cn=Basic OCSP CA
responder.1.signer.1.certificate=c=SE,cn=Basic OCSP Signer
responder.1.signer.1.pin=1234
responder.1.forwarding.enabled = true
responder.1.forwarding.onlyforissuer.1=*

; Configure the ocsp client for this responder
responder.1.forwarding.client.request.usecache=false
responder.1.forwarding.client.request.http.method=post
responder.1.forwarding.client.request.signature.chain=none
responder.1.forwarding.client.response.allowunknown=true
responder.1.forwarding.client.response.signature.check=false
responder.1.forwarding.client.response.chain.validate=false
responder.1.forwarding.client.urlcheck.1 = table
responder.1.forwarding.client.urlcheck.1.table.1.url = http://otherhost:8080/
responder.1.forwarding.client.urlcheck.1.table.1.issuermatch = *

; Specify the PKCS#12 key store for the signing certificate.
key.store.store.1=basic-ca-signer.p12
key.store.store.1.pin=secretPIN1234

Use this sample configuration to set up Nexus OCSP Responder to forward all incoming OCSP requests to another (OCSP) responder using client authentication:

Example 2

CODE

; This rsponder supports all CAs and forwards to another responder
responder.1.type=basic
responder.1.url=http://*:8080/1
responder.1.workers=5
responder.1.signature.chain=cert
responder.1.signer.1.issuerdn=c=SE,cn=Basic OCSP CA
responder.1.signer.1.certificate=c=SE,cn=Basic OCSP Signer
responder.1.signer.1.pin=1234
responder.1.forwarding.enabled = true
responder.1.forwarding.onlyforissuer.1 = *

; Configure the ocsp client for this responder
responder.1.forwarding.client.urlcheck.1 = table
responder.1.forwarding.client.urlcheck.1.table.1.url = https://otherhost:8444
responder.1.forwarding.client.urlcheck.1.table.1.issuermatch = *
responder.1.forwarding.client.authentication.key.certificate=c=SE,cn=TLS Client
responder.1.forwarding.client.authentication.key.pin=1234

; Specify the PKCS#12 key store for the signing and TLS certificate.
key.store.store.1=basic-ca-signer.p12
key.store.store.1.pin=secretPIN1234
key.store.store.2=tls-client.p12
key.store.store.2.pin=1234

Specify the OCSP responders

Specify limitations on incoming requests

Specify responder and responses

Specify billing information

Specify forwarding of requests

Example:

Specify freshness proof

Specify system control

Specify ping data

Examples

View examples

Nexus OCSP responder configuration

Nexus OCSP responder proxy configuration

Example 1

Example 2

Related information