NaviServer - programmable web server
4.99  5.0

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

nsssl(n) 4.99.30 nsssl "NaviServer Modules"

Name

nsssl - Configuring HTTPS socket communications

Table Of Contents

Description

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.

CONFIGURATION

This module support all configuration options of nssock module, plus in addition the following configuration options:

certificate

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 55935 1    ;# SIGHUP has signal number 1
ciphers

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

ciphersuites

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

protocols

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.

verify

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.

OCSPstapling

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.

OCSPstaplingVerbose

Optionally make OCSP requests more verbose in the log file.

extraheaders

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.

EXAMPLES

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.

See Also

ns_http, ns_log, ns_write

Keywords

HTTPS, TCP_FASTOPEN, configuration, driver, module, nsssl, performance, signal, tuning