nsssl - Configuring HTTPS socket communications
The driver module nsssl is used for the socket communication over HTTPS. The module shares the configuration parameters of nssock and adds additional parameters. This driver requires a NaviServer installation with the configuration option --with-openssl enabled.
This module support all configuration options of nssock module, plus in addition the following configuration options:
is a required parameter, nsssl won't load without it. The parameter points to a file containing certificates, which must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA. The PEM file cem can contain DH parameters (see the example below how to add these).
When the server receives a hangup signal (HUP), the certificates and private keys are reloaded without server restart. The signal can be send also from a script executed in the server:
ns_kill 89237 1 ;# SIGHUP has signal number 1
defines which ciphers will be used. The ciphers are defined in the OpenSSL "CIPHER LIST FORMAT" https://www.openssl.org/docs/manmaster/apps/ciphers.html. By default nsssl uses all ciphers; recommended cipher suites are published on various sources, such as e.g.: https://wiki.mozilla.org/Security/Server_Side_TLS
defines which ciphersuites for TLSv1.3 (and probably beyond). Due to the major differences between ciphersuites up to TLSv1.2 OpenSSL has decided to configure ciphersuited for TLSv1.3 differently, by using this parameter. For details, consult: https://wiki.openssl.org/index.php/TLS1.3
defines which protocols are enabled; by default all protocols are enabled. It is recommended to deactivate SSLv2 and SSLv3 as shown in the example above.
specifies, whether nsssl should send a client certificate request to the client. The certificate returned (if any) is checked. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure.
This parameter activates OCSP Stapling for TLS/SSL connections (default off). OCSP Stapling allows a client to check during connection startup the state of the server certificate at the server of the issuer of the certificate (in particular, whether the certificate was revoked or not).
NaviServer performs two level of caching: in-memory caching and disk caching. When the server receives the first TLS request with OCSP stapling turned on, it checks for an already retrieved OCSP response. The disk cache file is saved in the "log" directory of the server and uses the serial number of the certificate to be checked as filename with ".der" as extension. When the disk cache file does not exist, an HTTP/HTTPS request is made to the server issuing the servers certificate as defined by the Authority Information Access (AIA) Extension. The names of the file and the HTTP/HTTPS request for the OCSP response can be obtained from the system log of the server:
... ... Warning: OCSP cache file does not exist: /usr/local/ns/logs/XXX.der ... ... Notice: OCSP command: ns_http run http://ocsp.int-x3.letsencrypt.org/YYYY ...
Note that the .der file can be obtained as well by other means, e.g. via the program "curl". In case an application requires OCSP stapling and the server cannot make requests to the external server e.g. a cron tab can refresh the .der file regularly.
curl http://ocsp.int-x3.letsencrypt.org/YYYY --output /usr/local/ns/logs/XXX.der
For more details about OCSP, see: https://tools.ietf.org/html/rfc6960 OCSP support requires OpenSSL 1.1.0 or newer.
Optionally make OCSP requests more verbose in the log file.
specify the directory for lookup of certificates for mass virtual hosting (see admin-config).
can be used to specify additional header fields be sent on every request handled by this driver. The example above, HTTP Strict Transport Security (HSTS) is enabled.
The module is typically loaded per server (specified below in the variable "server"):
ns_section ns/server/$server/modules {
ns_param nsssl nsssl.so
}
ns_section ns/server/$server/module/nsssl {
ns_param certificate /usr/local/ns/modules/nsssl/server.pem
ns_param address 0.0.0.0
ns_param port 443
ns_param ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384"
ns_param ciphersuites "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"
ns_param protocols "!SSLv2:!SSLv3:!TLSv1.0:!TLSv1.1"
ns_param OCSPstapling on
ns_param verify 0
ns_param extraheaders {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Frame-Options SAMEORIGIN
X-Content-Type-Options nosniff
}
}
This amount of configuration is sufficient for many installations, but often one needs different security setting (path the to certificate, port, ciphers, etc.) or additional settings from nssock such as e.g. writerthreads, maxinput or maxupload.
Below is an example, how a web site can create a self-signed certificate in PEM format. The last line with the DH parameters is optional but necessary for achieving perfect forward secrecy.
openssl req -new -x509 -sha256 -newkey rsa:2048 -days 365 -nodes -keyout host.key.pem -out host.cert.pem cat host.cert.pem host.key.pem > server.pem rm host.cert.pem host.key.pem openssl dhparam 2048 >> server.pem
For discussion and more examples see admin-config.