SSL Directives

ListenSecure

Description IP address and port on which to listing for incoming SSL/TLS requests.
Synopsis ListenSecure [IP address:]portNumber [multiple]
Context Default server, Virtual Host
Examples Listen 80
ListenSecure 205.162.77.64:7777
ListenSecure :7777 multiple
ListenSecure [::]
Notes

The ListenSecure directive specifies the IP endpoints on which Appweb will listen for incoming SSL/TLS HTTP requests. If you specify only the port number and omit the IP address, Appweb will listen on all network interfaces including the loop-back adaptor. Multiple Listen directives may be given and Appweb will listen on all the specified endpoints for SSL/TLS.

In Appweb 4 and later, you do not need to use a Virtual Host to use SSL/TLS.

For IPv6 endpoints, enclose the IP address in square brackets. For example: Listen [2001:05c0:9168:0000:0000:0000:0000:0001]

To permit multiple instances of Appweb to bind to the same listen endpoint, specify the multiple attribute. Multiple binding is supported on Linux only.

SSLProtocol

Description Restrict the SSL protocols for OpenSSL.
Synopsis SSLProtocol [+ | -] protocol ...
Context OpenSSL only. Default Server, Virtual Host
Example SSLProtocol ALL -SSLv2 -SSLv3 -TLSv1.0
Notes

The SSLProtocol directive defines which SSL protocol variants to enable for use. The following protocol options are available:

SSLv2

This is the original Secure Sockets Layer (SSL) protocol defined by Netscape. It has several flaws and should not be used if SSLv3 or TLSv1 are available.

SSLv3

This is the Secure Sockets Layer (SSL) protocol version 3.

TLSv1/h3>

This enables all TSLv1 including versions 0, 1, 2 and 3.

TLSv1.0/h3>

This is an early TLS protocol and should not be used if TLSv1.2 and TLSv1.3 are available.

TLSv1.1, TLSv1.2 or TLS1.3

These are the current versions of the Transport Layer Security (TLS) protocol recommended by the IETF and should be used if available.

ALL

Enables all SSL protocol variants.

If unspecified, the default is: TLSv1.1 | TLSv1.2 | TLSv1.3.

Security

You should not use SSLv2 if possible.

SSLCipherSuite

Description Defines the permissible SSL Cipher suites.
Synopsis SSLCipherSuite cipher-spec
Context Default Server, Virtual Host
Example #
# For most SSL stacks
#
CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA
CipherSuite TLS_RSA_WITH_RC4_128_SHA

#
# For OpenSSL
#
CipherSuite HIGH:RC4+SHA
Notes

The SSLCipherSuite directive specifies the permissible set of cipher algorithms to use when communicating with the client. If unspecified, the cipher suite is defined by the SSL protocol stack and negotiated with the client. You may use this directive multiple times or may specify multiple ciphers separated by commas. This directive is not supported with all SSL stacks.

The format of this directive varies depending on the SSL protocol stack. The OpenSSL stack uses its own proprietary cipher naming. If using OpenSSL, please consult the OpenSSL documentation for how to format the cipher suite argument. Other SSL stacks use IANA Cipher Suite Registry names.

SSLCertificateFile

Description Defines the location of the X.509 file containing the server certificate
Synopsis SSLCertificateFile path
Context Default Server, Virtual Host
Example SSLCertificateFile /var/appweb/server.crt
Notes

The SSLCertificateFile directive defines the file containing the PEM encoded X.509 certificate for the server. The file may also contain the private key for the server in which case you do not need to use the SSLCertificateKeyFile directive.

The path may be an absolute path or it may be relative to the Home directory.

SSLCertificateKeyFile

Description Defines the location of the server's private key
Synopsis SSLCertificateKeyFile
Context Default Server, Virtual Host
Example SSLCertificateKeyFile /var/appweb/server.key.pem
Notes

The SSLCertificateKeyFile directive defines the file containing the PEM encoded private key file for the server. This directive is not required if the server's private key is combined with the certificate file.

If the private key is encrypted, you will be prompted to enter the pass-phrase to decrypt the private key on system reboot.

Security There is a dilemma here. If you use an encrypted private key, the server will pause until you enter the pass-phrase which makes headless operation impossible. If you do not encrypt the private key, your private key is more vulnerable should the server be compromised. Which option you choose depends on whether headless operation is essential or not.

SSLCACertificateFile

Description Defines the location of the certificate file for client authentication
Synopsis SSLCACertificateFile path
Context Default Server, Virtual Host
Example SSLCACertificateFile /var/appweb/ca.crt
Notes

The SSLCACertificateFile directive defines the file containing the certificates to use when authenticating client certificates. This directive is only necessary if you wish to verify client certificates. If so, you must specify the "SSLVerifyClient on" directive.

The certificate file contains the concatenated certificates to use in preference order. The path may be an absolute path or it may be relative to the Home directory.

If using the OpenSSL stack, You may alternatively use SSLCACertificatePath if you have separate certificates.

SSLCACertificatePath

Description Defines a directory of client authentication certificates.
Synopsis SSLCACertificatePath
Context OpenSSL only. Default Server, Virtual Host
Example SSLCACertificatePath /var/appweb/certs
Notes

The SSLCACertificatePath directive is an OpenSSL directive that defines the directory containing the certificates to use when authenticating client certificates. This directive is only necessary if you wish to verify client certificates. If so, you must specify the "SSLVerifyClient on" directive.

The path may be an absolute path or it may be relative to the Home directory.

This directive is only supported for OpenSSL. If using another SSL stack, you may use SSLCACertificateFile if you have a bundle of certificates concatenated together.

SSLEngine

Description Define an OpenSSL Engine to use for the current context.
Synopsis SSLEngine
Context OpenSSL only. Default Server, Virtual Host
Example SSLEngine tpm2tss
Notes

The SSLEngine directive configures OpenSSL to use the nominated Openssl engine for the configured route.

SSLPreload

Description Preload the SSL configuration.
Synopsis SSLPreload
Context OpenSSL only. Default Server, Virtual Host
Example SSLPreload
Notes

The SSLPreload directive is an OpenSSL directive that will pre-create the required SSL configuration in anticipation of future SSL requests. This will minimize delays for the first SSL request received.

SSLVerifyClient

Description Defines the type of client certificate verification.
Synopsis SSLVerifyClient [off | on]
Context Default Server, Virtual Host
Example SSLVerifyClient on
Notes

This directive controls whether the client must provide a client certificate for the server to verify the identity of the client. If set to off, no certificate is required. If one is supplied, it will be ignored. The certificate and the certificate's issuer will be verified. Use the SSLVerifyIssuer directive to turn off verification of the issuer if you need to use a self-signed test certificate.

If the directive is set to on, the client must provide a valid certificate.

SSLVerifyIssuer

Description Defines whether the issuer of the client certificate is verified.
Synopsis SSLVerifyIssuer [off | on]
Context Default Server, Virtual Host
Example SSLVerifyIssuer on
Notes

This directive controls whether the issuer of the client certificate will be verified. If set to off, the certificate issuer will not be verified. This is useful to accept self-signed test certificates.

© Embedthis Software. All rights reserved.