lighttpd2/doc/mod_openssl.xml

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:lighttpd.net:lighttpd2/doc1">
	<short>listens on separate sockets for TLS connections (https) using OpenSSL</short>

	<setup name="openssl">
		<short>setup a TLS socket</short>
		<parameter name="options">
			<table>
				<entry name="listen">
					<short>(mandatory) the socket address to listen on (same as "listen":plugin_core.html#plugin_core__setup_listen), can be specified more than once to setup multiple sockets with the same options</short>
				</entry>
				<entry name="pemfile">
					<short>(mandatory) file containing the private key, certificate and (optionally) intermediate certificates (the root certificate is usually not included)</short>
				</entry>
				<entry name="ca-file">
					<short>file containing the intermediate certificates</short>
				</entry>
				<entry name="ciphers">
					<short>OpenSSL ciphers string (default: "HIGH !aNULL !3DES +kEDH +kRSA !kSRP !kPSK")</short>
				</entry>
				<entry name="dh-params">
					<short>filename with generated dh-params (default: fixed 4096-bit parameters)</short>
				</entry>
				<entry name="ecdh-curve">
					<short>OpenSSL ecdh-curve name</short>
				</entry>
				<entry name="options">
					<short>list of OpenSSL options (default: NO_SSLv2, NO_SSLv3, CIPHER_SERVER_PREFERENCE, NO_COMPRESSION, SINGLE_DH_USE, SINGLE_ECDH_USE)</short>
				</entry>
				<entry name="verify">
					<short>enable client certificate verification (default: false)</short>
				</entry>
				<entry name="verify-any">
					<short>allow all CAs and self-signed certificates, for manual checking (default: false)</short>
				</entry>
				<entry name="verify-depth">
					<short>sets client verification depth (default: 1)</short>
				</entry>
				<entry name="verify-require">
					<short>abort clients failing verification (default: false)</short>
				</entry>
				<entry name="client-ca-file">
					<short>file containing client CA certificates (to verify client certificates)</short>
				</entry>
			</table>
		</parameter>

		<description>
			<textile>
				For @ciphers@ see OpenSSL "ciphers":https://www.openssl.org/docs/manmaster/man1/ciphers.html string

				For @options@ see "options":https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html. Explicitly specify the reverse flag by toggling the "NO_" prefix to override defaults.
			</textile>
		</description>

		<example title="Simple TLS on IPv4 and IPv6">
			<config>
				setup {
					module_load "mod_openssl";
					openssl [
						"listen" => "0.0.0.0:443",
						"listen" => "[::]:443",
						"pemfile" => "/etc/certs/lighttpd.pem",
						"options" => ["ALL", "NO_TICKET"],
					];
				}
			</config>
		</example>

		<example title="TLS with client certificate verification">
			<config>
				setup {
					module_load "mod_openssl";
					openssl (
						"listen" => "0.0.0.0:443",
						"listen" => "[::]:443",
						"pemfile" => "/etc/certs/lighttpd.pem",
						"client-ca-file" => "/etc/certs/myCA.pem",
						"verify" => true,
						"verify-require" => true
					);
				}
			</config>
		</example>

		<example title="TLS with any client certificate">
			<config>
				setup {
					module_load "mod_openssl";
					openssl (
						"listen" => "0.0.0.0:443",
						"listen" => "[::]:443",
						"pemfile" => "/etc/certs/lighttpd.pem",
						"verify" => true,
						"verify-any" => true,
						"verify-depth" => 9
					);
				}
				openssl.setenv "client-cert";
			</config>
		</example>
	</setup>

	<action name="openssl.setenv">
		<short>set SSL environment strings</short>
		<parameter name="list">
			<short>list of subsets to export</short>
		</parameter>
		<description>
			<textile>
				Supported subsets:
				* "client"      - set @SSL_CLIENT_S_DN_@ short-named entries
				* "client-cert" - set @SSL_CLIENT_CERT@ to client certificate PEM
				* "server"      - set @SSL_SERVER_S_DN_@ short-named entries
				* "server-cert" - set @SSL_SERVER_CERT@ to server certificate PEM
			</textile>
		</description>
	</action>
</module>