Configuring an HTTPS handler

How to configure an HTTPS handler to manage HTTPS requests to DataPower® services. When the handler supports the WebSocket protocol, the handler accepts requests that use the https or wss protocol identifier.

About this task

You can configure a handler to support the WebSocket or HTTP version 2 (HTTP/2) protocol. A client cannot have both a WebSocket and an HTTP/2 session. WebSocket cannot use an HTTP/2 session. The establishment of an HTTP/2 session disables the WebSocket upgrade.
  • For a WebSocket upgrade, the request is to switch the existing connection to use the WebSocket protocol. WebSocket upgrade requests require that the handler allows GET methods in requests. When the handler switches to the WebSocket protocol, you can control the idle timeout. This timer monitors the idle time in the data transfer process. When the specified idle time is exceeded, the connection is torn down.
    Attention: Not all DataPower services support WebSocket upgrade. If you assign a handler that supports WebSocket upgrade to a DataPower service that does not, the DataPower service cannot start because of an invalid configuration.
  • For HTTP/2, the handler must allow the HTTP/2 feature. When the handler uses the HTTP/2 protocol, you can control the following settings.
    • The maximum number of outstanding concurrent streams.
    • The maximum size in octets of frames.
    • Whether to enable the inclusion of the HTTP/2 stream header in the request or response. When enabled, the HTTP/2 stream identifier is included in the x-dp-http2-stream header. With this header, you can correlate the HTTP/2 stream.
    • The maximum idle duration in seconds to allow before the handler closes the HTTP/2 connection.
    However, you cannot control the following settings.
    • The HTTP version to clients.
    • The negotiation and reuse of persistent connections.
    • Upgrade to WebSocket.
The TLS profile that secures the HTTP/2 connection must prevent renegotiation and must use the TLS 1.2 or later protocol with a cipher that is secure according to RFC 7540. To prevent client-initiated TLS renegotiation, define the configuration as follows on the Advanced tab.
  • Set the Set max number client-initiated renegotiation allow option of the Advanced TLS options property.
  • Make sure that the value for the Max client-initiated renegotiations property is 0.

Alternatively, for only a TLS server profile, make sure that the Prohibit session resumption on renegotiation property is not enabled. This setting is the default setting.

For more information about the HTTP/2 protocol, see RFC 7540, RFC 7541, and RFC 8740.

Procedure

  1. In the search field, enter https.
  2. From the search results, click HTTPS handler.
  3. Click Add.
  4. Define the basic properties - Name, administrative state, and comments.
  5. Define connections from clients to the handler.
    1. In the Local IP address field, enter the IP address or host alias that the handler listens.
      To use a local host alias, click Select alias. A host alias resolves an alias to a static IP address. Aliasing can help when you move configurations among DataPower instances.
    2. In the Port field, enter the local port that the service listens.
  6. Optional: From the Allowed methods and versions list, select the methods and versions to allow in client requests.
  7. Optional: Define use of the WebSocket protocol.
    1. Set Allow WebSocket upgrade to control whether to allow requests with WebSocket Upgrade headers.
    2. In the WebSocket idle timeout field, enter the maximum idle time for client connections.
  8. Select the TLS server profile from the TLS server profile or TLS SNI server profile list to secure connections.

Click the Advanced tab to define or modify connection details.

  1. Optional: From the HTTP version to client list, select the version for client connections.
  2. Optional: Define whether to negotiate persistent connections and connection reuse.
    1. Set Negotiate persistent connections to control the negotiation of persistent connections.
    2. In the Max persistent reuse field, enter the maximum number of times a persistent connection is reused.
  3. Optional: Set Enable compression to control the negotiation of GZIP compression.
  4. Optional: Define HTTP header and URL limits.
    1. In the Max URL length field, enter the length of the longest incoming URL to accept.
      The length includes any query string or fragment identifier.
    2. In the Max total header length field, enter the maximum aggregate size of incoming HTTP headers.
    3. In the Max number of headers field, enter the maximum number of headers to allow in requests.
    4. In the Max header name length field, enter the maximum length of the name part of a header.
      Each HTTP header is expressed as a name-value pair.
    5. In the Max header value length field, enter the maximum length of the value part of a header.
      Each HTTP header is expressed as a name-value pair.
    6. In the Max query string length field, enter the maximum length of the query string.
      The query string is the portion of the URL after the ? character.
  5. Optional: From the Access control list list, select the ACL to apply.
  6. Optional: From the Credential character set list, select the character encoding of the original basic authentication values.
  7. Optional: Define limits for HTTP/2 protocol upgrades.
    1. In the HTTP/2 max streams field, specify the maximum number of outstanding concurrent streams that the client can have. Enter a value in the range 1 - 500. The default value is 100.
    2. In the HTTP/2 max frame size field, specify the maximum frame size in octets that the client can send. Enter a value in the range 16384 - 16777215. The default value is 16384.
    3. Set the Enable HTTP/2 stream header property to include the HTTP/2 stream identifier header in the request or response. By default, the header is excluded.
    4. In the HTTP/2 idle timeout field, specify the maximum idle duration to allow in seconds before the handler closes the HTTP/2 connection. Enter a value in the range 0 - 3600000, where a value of 0 disables the timer. The default value is 0.
  8. Optional: Set the Enable chunked encoding responses property to use the Transfer-Encoding: chunked header in responses to clients.
  9. Optional: In the Request headers processing timeout field, enter the maximum duration in milliseconds to allow for request headers processing. When the value is greater than 0, request header processing must complete before the duration elapses. Enter a value in the range 0 - 3600000, where a value of 0 disables the timer. The default value is 30000.
  10. Click Apply to save changes to the running configuration.
  11. Click Save to save changes to the persisted configuration.