NaviServer Modules – 5.0.4
nsssl - Network Driver for 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 the server certificate chain in PEM format. The file must be sorted starting with the subject's certificate (actual server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA. The PEM file can contain DH parameters (see the example below how to add these).
When the server receives a hangup signal (HUP), the certificate and private key are reloaded without server restart. The signal can be send also from a script executed in the server:
ns_kill [pid] 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 request and verify a client certificate during the TLS handshake.
When this parameter is set to true, the server sends a CertificateRequest message to the client and attempts to verify the returned client certificate against the configured trusted client certificate authorities. If no client certificate is provided, or if verification fails, the connection is terminated. This parameter applies at the driver level and therefore affects all TLS contexts created by this driver, including dynamically created virtual hosts (see below).
Note: The verify parameter is a legacy boolean switch. Future versions may replace it with a more fine-grained control (e.g., optional vs. required client certificates).
Specifies a file containing trusted Certificate Authority (CA) certificates used to validate client certificates. The file must be in PEM format and may contain one or more CA certificates. These certificates are used both:
to verify the certificate chain presented by the client, and
to advertise acceptable client certificate issuers to the client during the TLS handshake.
If this parameter is not specified, no explicit client CA list is configured. In this case, client certificate verification may fail, or clients may not offer a certificate even when requested. The value can be a relative name (relative to NaviServer home) or can be specified as an absolute path.
Specifies a directory containing trusted Certificate Authority (CA) certificates used to validate client certificates. The directory must be prepared with openssl rehash so that OpenSSL can locate certificates via hashed symbolic links. This parameter can be used as an alternative or in addition to clientcafile. The value can be a path relative to NaviServer home or an absolute path.
If both clientcafile and clientcapath are provided, both locations are used for certificate verification.
The configuration parameters verify, clientcafile, and clientcapath are evaluated at the driver level. All TLS contexts created by the driver inherit these settings. This includes TLS contexts created dynamically for mass virtual hosting via the vhostcertificates directory.
Consequently, enabling verify affects all virtual hosts served by the driver. All such hosts will require client certificates to be presented and successfully verified.
Currently, it is not possible to configure client certificate verification on a per-virtual-host basis. All virtual hosts share the same verification policy and trusted client CA configuration. Future extensions may allow per-host configuration via name-based configuration files associated with virtual host certificates.
ns_section ns/server/$server/module/https {
ns_param verify 1
ns_param clientcafile /usr/local/ns/client-ca.crt
# ns_param clientcapath /usr/local/ns/client-ca
}
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 https nsssl.so
}
ns_section ns/server/$server/module/https {
ns_param certificate /usr/local/ns/modules/https/server.pem ;# required, PEM format
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.