The HTTPS Connector

Introduction

The HTTPS Connector element represents a Connector component that supports the HTTP/1.1 protocol. SSL, or Secure Socket Layer, is a technology which allows web browsers and web servers to communicate over a secured connection. This means that the data being sent is encrypted by one side, transmitted, then decrypted by the other side before processing. This is a two-way process, meaning that both the server AND the browser encrypt all traffic before sending out data.

Attributes

Common Attributes

See the http connector documentation for the commun attributs.

Attribute Description
ssl
Use this element to enable SSL traffic on a connector. To turn on SSL handshake/encryption/decryption on a connector. When present you will want to set the scheme and the secure attributes as well to pass the correct request.getScheme() and request.isSecure() values to the servlets.

scheme
Set this attribute to the name of the protocol you wish to have returned by calls to request.getScheme(). For example, you would set this attribute to "https" for an SSL Connector. The default value is "http".

secure
Set this attribute to true if you wish to have calls to request.isSecure() to return true for requests received by this Connector. You would want this on an SSL Connector or a non SSL connector that is receiving data from a SSL accelerator, like a crypto card, a SSL appliance or even a webserver. The default value is false.

Standard Implementation

HTTPS doesn't support more attributes that the ones listed above.

Nested Components

ssl is the nested component of the https connector.

Special Features

HTTP/1.1 and HTTP/1.0 Support

This Connector supports all of the required features of the HTTP/1.1 protocol, as described in RFC 2616, including persistent connections, pipelining, expectations and chunked encoding. If the client (typically a browser) supports only HTTP/1.0, the Connector will gracefully fall back to supporting this protocol as well. No special configuration is required to enable this support. The Connector also supports HTTP/1.0 keep-alive.

RFC 2616 requires that HTTP servers always begin their responses with the highest HTTP version that they claim to support. Therefore, this Connector will always return HTTP/1.1 at the beginning of its responses.

Proxy Support

The proxy-name and proxy-port attributes can be used when JBoss Web is run behind a proxy server. These attributes modify the values returned to web applications that call the request.getServerName() and request.getServerPort() methods, which are often used to construct absolute URLs for redirects. Without configuring these attributes, the values returned would reflect the server name and port on which the connection from the proxy server was received, rather than the server name and port to whom the client directed the original request.

For more information, see the Proxy Support HOW-TO.

SSL Support

You can enable SSL support for a particular instance of this Connector by setting the secure attribute to true. In addition, you may need to configure the following sslattributes:

Attribute Description
name
name of the ssl element.

verify-client
that is OpenSSL SSLVerifyClient (optional,require,optionalNoCA,none) and clientAuth (true=require/false=none)i

Set to true if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to want if you want the SSL stack to request a client Certificate, but not fail if one isn't presented. A false value (which is the default) will not require a certificate chain unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication. See the SSL HowTo for an example.

verify-depth Maximum number of intermediate certificate issuers checked before deciding that the clients don't have a valid certificate. The default value is "10".
certificate-key-file
The pathname of the keystore file where you have stored the server certificate to be loaded. When using JSSE that could be the only file, with OpenSSL there several files. By default, the pathname is the file "${user.home}/.keystore" in the operating system home directory of the user that is running JBoss Web. If your keystoreType doesn't need a file use "" (empty string) for this parameter.

certificate-file
Only in the OpenSSL (JSSE keystore contains both key and certificate). That is the name of the file containing the server certificate.

password
Password for both trustore and keystore The default value is "changeit".

protocol
The version of the SSL protocol to use. If not specified, Supported values: SSLv2, SSLv3, TLSv1, SSLv2+SSLv3 and ALL. the default is "ALL".

ciphers
A comma seperated list of the encryption ciphers that may be used, that MUST NOT be the JVM default in of JSSE as contains weak ciphers. that is SSLCipherSuite when using OpenSSL (APR). If not specified, then any available "safe" ciphers may be used.

key-alias
The alias used to for the server certificate in the keystore. the default is "tomcat".

ca-certificate-file
The file containing the CA certificates, truststoreFile in JSSE, note the password it same as the keystore password. The ca-certificate-file file to use to validate client certificates.

ca-certificate-file
A file or URL to get the revocation list. (actually: crlFile is JSSE and SSLCARevocationFile in OpenSSL)

session-cache-size
Size of the SSLSession cache. the default is 0: Dissabled.

session-timeout
Timeout of a cached SSLSession. the default is 86400: 24 hours.

For more information, see the SSL Configuration HOW-TO.

Attribute	Description
`ssl`	Use this element to enable SSL traffic on a connector. To turn on SSL handshake/encryption/decryption on a connector. When present you will want to set the `scheme` and the `secure` attributes as well to pass the correct `request.getScheme()` and `request.isSecure()` values to the servlets.
`scheme`	Set this attribute to the name of the protocol you wish to have returned by calls to `request.getScheme()`. For example, you would set this attribute to "`https`" for an SSL Connector. The default value is "`http`".
`secure`	Set this attribute to `true` if you wish to have calls to `request.isSecure()` to return `true` for requests received by this Connector. You would want this on an SSL Connector or a non SSL connector that is receiving data from a SSL accelerator, like a crypto card, a SSL appliance or even a webserver. The default value is `false`.

Attribute	Description
`name`	name of the `ssl` element.
`verify-client`	that is OpenSSL SSLVerifyClient (optional,require,optionalNoCA,none) and clientAuth (true=require/false=none)i Set to `true` if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to `want` if you want the SSL stack to request a client Certificate, but not fail if one isn't presented. A `false` value (which is the default) will not require a certificate chain unless the client requests a resource protected by a security constraint that uses `CLIENT-CERT` authentication. See the SSL HowTo for an example.
`verify-depth`	Maximum number of intermediate certificate issuers checked before deciding that the clients don't have a valid certificate. The default value is "`10`".
`certificate-key-file`	The pathname of the keystore file where you have stored the server certificate to be loaded. When using JSSE that could be the only file, with OpenSSL there several files. By default, the pathname is the file "`${user.home}/.keystore`" in the operating system home directory of the user that is running JBoss Web. If your `keystoreType` doesn't need a file use `""` (empty string) for this parameter.
`certificate-file`	Only in the OpenSSL (JSSE keystore contains both key and certificate). That is the name of the file containing the server certificate.
`password`	Password for both trustore and keystore The default value is "`changeit`".
`protocol`	The version of the SSL protocol to use. If not specified, Supported values: SSLv2, SSLv3, TLSv1, SSLv2+SSLv3 and ALL. the default is "`ALL`".
`ciphers`	A comma seperated list of the encryption ciphers that may be used, that MUST NOT be the JVM default in of JSSE as contains weak ciphers. that is SSLCipherSuite when using OpenSSL (APR). If not specified, then any available "safe" ciphers may be used.
`key-alias`	The alias used to for the server certificate in the keystore. the default is "`tomcat`".
`ca-certificate-file`	The file containing the CA certificates, truststoreFile in JSSE, note the password it same as the keystore password. The `ca-certificate-file` file to use to validate client certificates.
`ca-certificate-file`	A file or URL to get the revocation list. (actually: crlFile is JSSE and SSLCARevocationFile in OpenSSL)
`session-cache-size`	Size of the SSLSession cache. the default is `0`: Dissabled.
`session-timeout`	Timeout of a cached SSLSession. the default is `86400`: 24 hours.