OCSP responder section
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.
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:
CODEresponder.<r#>.type=[basic|cached|identrus-basic|identrus-cached|non-issued-basic|non-issued-cached] responder.<r#>.url=[http|https]://<host>[:<port>][/<path>] 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] 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] responder.<r#>.archivecutoff=[true|false]
See this table for description of constants and values:
Constants and Values Description <r#>
Replace <r#>
with the responder sequence number.basic | cached | identrus-basic | identruscached | non-issued-basic | non-issuedcached
- 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 nonextUpdate
in OCSP responses. - Enter
identruscached
to add capabilities to those of basic for checking of the response cache, freshness proof and nonextUpdate
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.
http | https
- Enter
http
to indicate that the HTTP protocol shall be used (TLS is not needed). - Enter
https
to indicate that the HTTPS protocol shall be used (TLS is needed).
<host>[:<port>][/<path>]
Replace
<host>
with the address of the network interface the responder shall listen to. Use "*" if the responder should listen to all the interfaces on this host. If needed, specify also the port and path.Default: The port defaults to 80 when HTTP is used and to 443 for HTTPS.
true | false
for parameter..ssl.clientauth
- If client TLS authentication is required, set this to
true
(HTTPS only). - If client TLSauthentication is not required, set this to
false
.
Default:
false
<certificate pattern>
for parameter..ssl.certificate
See Key management section for
more information.<PIN>
for parameter..ssl.pin
See Key management section for
more information.<cipher suites>
for parameter..ssl.cipher
A comma separated list of TLS cipher suites that should be enabled.
If HTTPS is enabled, then limit the number of enabled cipher suites to a subset of the default. By default, all the supported cipher suites of Java's SunJSSE provider described in Java Secure Socket Extension (JSSE) Reference Guide for JDK 11 under the section "SunJSSE provider", are enabled.
<protocols>
for parameter..ssl.protocol
A comma separated list of TLS protocols that should be enabled.
If HTTPS is enabled, then limit the number of enabled protocols to a subset of the default. By default all the supported protocols of Java's SunJSSE provider described in Java Secure Socket Extension (JSSE) Reference Guide for JDK 11 under the section "SunJSSE provider", are enabled.
<# of connections>
Replace
<# of connections>
with the number of allowed connections that can be handled simultaneously. If not specified then the default value of 2000 allowed connections will be set.<# of workers>
Replace <# of workers>
with the number of requests that can be handled simultaneously. The optimal value depends on the number of processors, processing power and memory.<socketreadtimeout>
Replace
<socketreadtimeout>
with a time period expression (short form), specified according to ISO 8601 Representation of dates and times. 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
<algorithmname>
Replace
<algorithmname>
with the requested signature algorithm to sign the response with. The names of the available algorithms are described in Java Cryptography Architecture Standard Algorithm Name Documentation for JDK 11 under the section "Signature Algorithms".If not defined, the signing algorithm will default to
SHA256with<RSA|ECDSA|DSA>
or to the algorithm parameter defined in the public key, that is,RSASSA-PSS
.true | false
for parameter...forwarding.enabled
Enter
true
to perform,false
not to perform forwarding of requests. This enables additional configuration. Read more in "Specify forwarding of requests" below.Default: false.
<s#>
Replace <s#>
with the signer sequence number.<distinguished name>
Replace <distinguished name>
with the exact distinguished name of the certificate present in the trust store for the issuer to be supported. Run the certadmlist
command to get the syntactically correct distinguished name of each issuer in the trust store. Copying part of the output of that command into the configuration is the recommended way to go when altering the configuration file. See Trust store for further information on how to use the certadm tool.<certificate pattern>
Replace <certificate pattern>
with the certificate pattern needed to specify the key pair for either the signer or the certificate used for HTTPS. See Key management section for information on how to specify a key. Note that this signer must be the issuer itself, or issued by the certificate specified inissuerdn
. For a description of the syntax, see Introduction to LDAP.<PIN>
Replace <PIN>
with the PIN for the key pair used with either the signer or the HTTPS certificate. See Key management section for information on how to specify a key. To encrypt the pin, see Encryption of sensitive configuration parameters.true | false
for parameter...setnextupdate
Enter true
to include,false
not to include theNextUpdate
attribute in the response for this signer. Default istrue
.true | false
for parameter...archivecutoff
Enter true
to include,false
not to include theArchiveCutoff
extension in the response for this responder. The extension will use the value from theExpiredCertsInCrl
extension in the CRL and will only be added if such extension is found. Default isfalse
.- Enter
To read more regarding access control, see Access control and billing.
Specify limitations on the incoming requests to the OCSP responder as follows:
Signature required
CODEresponder.<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:CODEresponder.<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:
CODEresponder.<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. - Enter
In the OCSP configuration file, specify as follows:
CODEresponder.<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 extensionExtendedKeyUsage
of the signature certificate(s).Default:
true
If this parameter is set to
true
andExtendedKeyUsage
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 tonone
.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 tochain
orallchains
.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
- Enter
Billing is described in Access control and billing.
In the OCSP configuration file, specify as follows:
Specify billing
CODEresponder.<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, orfalse
to not include responses with the status "unknown" in logging forpercert
.Default:
false
true | false
for parameter...billing.includestatus
Enter
true
to include, orfalse
to not include certificate status in logging forpercert
.Default:
false
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
withresponder.<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.
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
CODEresponder.<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.CODEresponder.<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
CODEresponder.<r#>.forwarding.responseWhenInvalidResponseFromBackEndClient=[unknown|trylater|internalerror]
For a description of the freshness proof functionality, see Freshness proof.
In the OCSP configuration file, specify as follows for
type=identrus-cached
:CODEresponder.<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
If you add freshness proof, be sure that you have specified OCSP response cache renewing. For more information see OCSP response cache section.
The freshness proof process 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#>.freshnessproof.client
where <r#>
is the responder sequence number.
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:
CODEresponder.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
.
In the OCSP configuration file, specify ping data as follows:
CODEresponder.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
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.
Example: Nexus OCSP Responder configuration
; 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: Nexus OCSP Responder proxy configuration
; 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: Nexus OCSP responder proxy configuration
; 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
Related information
- Access control and billing
- Back end client section
- Configure Nexus OCSP Responder
- Distinguished name matching
- Freshness proof
- Key management section
- Introduction to LDAP
- Nexus OCSP Responder
- OCSP response cache section
- Trust store
- Java Cryptography Architecture Standard Algorithm Name Documentation for JDK 8