PKI 10.6 HTTP NIO Connector Support - dogtagpki/pki GitHub Wiki
In version 10.5 PKI relies on JSS to handle HTTPS connection. The problem is, the current JSS only works with blocking I/O (BIO) connector which is only available until Tomcat 8.0. In Tomcat 8.5 the BIO connector is no longer available, so it is necessary to switch to the non-blocking I/O (NIO) connector, which is available in Tomcat 8.0 and 8.5.
There are two ways to support NIO connector:
-
switch to JSSE NIO connector
-
implement JSS NIO connector
Tomcat provides a built-in JSSE NIO connector that can be used by PKI server, but it has some limitations. Due to its relative simplicity, this will be used as an initial solution for PKI 10.6.
To use JSSE NIO connector, the SSL connector element in server.xml needs to configured as follows:
<Connector name="Secure"
port="8443"
protocol="org.dogtagpki.tomcat.Http11NioProtocol"
SSLEnabled="true"
sslProtocol="SSL"
...
keystoreType="pkcs12"
keystoreFile="/var/lib/pki/pki-tomcat/conf/keystore.p12"
keystorePassFile="/var/lib/pki/pki-tomcat/conf/keystore.pwd"
keyAlias="sslserver"
trustManagerClassName="org.dogtagpki.tomcat.PKITrustManager"
/>
The protocol="org.apache.coyote.http11.Http11Protocol" should be replaced with protocol="org.dogtagpki.tomcat.Http11NioProtocol"
The sslImplementationName="org.apache.tomcat.util.net.jss.JSSImplementation" should no longer be specified, so the connector will use JSSE instead of JSS.
Since this element still contains JSS configuration attributes (e.g. ocspResponderURL, sslRangeCiphers, certdbDir), the connector will use org.dogtagpki.tomcat.Http11NioProtocol to pass these attributes to JSS.
Since the connector does not support JSS, the SSL server certificate and key needs to be provided to the connector via a PKCS #12 keystore instead of NSS database.
To validate SSL client certificates, the connector will use org.dogtagpki.tomcat.PKITrustManager to validate the client certificate against the CA certificates in the NSS database.
This configuration change will be done automatically by the pki-server migrate tool when the server is restarted.
For normal installation, the SSL server certificate and key will be automatically exported into a PKCS #12 keystore on each server startup. There are no additional steps required.
For installation with HSM, if the HSM supports key export, the SSL server certificate and key will be automatically exported into PKCS #12 keystore as well. However, if the HSM does not support key export, the SSL server certificate and key must be created in the internal token so it can be exported into PKCS #12 keystore. pkispawn will need to support installation with certificates stored in different tokens. This can be done by specifying the following pkispawn parameter:
pki_sslserver_token=internal
If Nuxwdog is enabled on the server, the server will no longer have the NSS database password to export the SSL server certificate and key. So, the admin will need to exported it manually before starting the server with the following commands:
-
Create a password file for PKCS #12 keystore
$ pki password-generate > "/var/lib/pki/pki-tomcat/conf/keystore.pwd" $ chown pkiuser.pkiuser "/var/lib/pki/pki-tomcat/conf/keystore.pwd" $ chmod 0660 "/var/lib/pki/pki-tomcat/conf/keystore.pwd"
-
Export SSL server certificate and key into PKCS #12 keystore
$ pki-server cert-export \
sslserver \
--instance "pki-tomcat" \
--pkcs12-file "/var/lib/pki/pki-tomcat/conf/keystore.p12" \
--pkcs12-password-file "/var/lib/pki/pki-tomcat/conf/keystore.pwd" \
--friendly-name "sslserver" \
--cert-encryption "PBE/SHA1/RC2-40" \
--key-encryption "PBE/SHA1/DES3/CBC"
$ chown pkiuser.pkiuser "/var/lib/pki/pki-tomcat/conf/keystore.p12"
$ chmod 0660 "/var/lib/pki/pki-tomcat/conf/keystore.p12"
This will only need to be done once, unless the certificate is renewed or rekeyed in the NSS database.
The upgrade procedure is documented in this page.
JSS may be able to provide a PKCS #11 keystore for the NIO connector. See also JSS KeyStore.
In order to work with NIO connector, TomcatJSS/JSS needs to implement the following classes:
Due to its complexity, this will be implemented in a later stage of PKI 10.6.