Options for connections

Options can be set, one at a time, by using the HWTHSET service. (See HWTHSET — Set HTTP connection or request options.)

HWTH_OPT_URI

The Uniform Resource Identifier (URI). This supplied buffer is the target location of the connection. This option is required for a connection.

Valid values are either an IPv4 or IPv6 address, or a hostname. Optionally, the hostname might be prefixed with the HTTP scheme (http://) or the HTTPS scheme (https://). Neither of the formats should be suffixed by a port specification. Instead the application should use the HWTH_OPT_PORT option to specify the port. In technical terms, specify only the authority portion of the URI, minus the port .

http://192.168.0.1
http://[2001:1890:1112:1::20]
http://www.example.com

When the URI value is provided in a hostname format in combination with the HWTH_OPT_USE_SSL = HWTH_SSL_USE, an automatic SNI extension is included during the connection negotiations. To enable an SNI extension, when the connection is secured by AT-TLS, see the ClientHandshakeSNI parameter of TTLSConnectionAdvancedParms statement in z/OS Communications Server: IP Configuration Reference.

Note: The toolkit accepts single-byte EBCDIC character data for the value of the URI option. The use of multibyte character encodings (such as UTF-8 and UTF-16) is not supported. For more information, see Code page consideration.

The toolkit indirectly supports Internationalized Domain Name (IDN). To specify a host name that contains Unicode characters, you must first apply the Punycode algorithm to covert the host name to an ASCII representation. (The Punycode algorithm converts each Unicode character outside of the US-ASCII character set to an encoded ASCII representation). After the entire host name string has been encoded as an ASCII sequence, it is necessary to convert to EBCDIC before passing in the HWTH_OPT_URI set option, since the toolkit expects all input data to be in EBCDIC.

HWTH_OPT_CERT_CHECK

An optional 4-byte integer value that tunes the level of checking performed and the return code severity in response a verification failure when checking the server’s identity within the server certificate. This option may be used to allow connections and redirects to a server that supplies a legacy certificate which does not contain a subjectAltName extension, or a certificate that does not accurately reflect the server identity.

The value for this option may be reset throughout the usage of the connection, for example, after HWTHCONN but before HWTHRQST, or between two consecutive HWTHRQSTs.

For more information about what verification is performed, see Server identity.

Valid values are:

HWTH_CERT_CHECK_SAN_ONLY

Verifies server identity in accordance with best practices defined by RFC 9110 sections 4.3.4 and 4.3.5. Only applicable subjectAltName extension entries (dnsName for DNS names and ipAddress for IP addresses) are used for server identification.

If the certificate provided by the server does NOT contain values that match the provided target identity, fails HWTHCONN and/or HWTHRQST with return code value of 262 decimal/'106'x.

HWTH_CERT_CHECK_SAN_CN_DNS

Verifies server identity in accordance with best practices defined by RFC 2818 section 3.1, which also permits legacy server certificates that are missing subjectAltName extension fields for DNS Names, and instead uses the Common Name (CN) field in the Subject for server identification in those cases.

If the certificate provided by the server does NOT contain values that match the provided target identity, fails HWTHCONN and/or HWTHRQST with return code value of 262 decimal/'106'x.

HWTH_CERT_CHECK_WARN

Uses rules described under HWTH_CERT_CHECK_SAN_ONLY for certificate verification.

If the certificate provided by the server does not contain values that match the provided target identity, completes HWTHCONN and/or HWTHRQST with return code value of 4. Once HWTHCONN and/or HWTHRQST have received a WARNING Start of change due to a certificate verification failure End of change , the WARNING will continue to be returned for all subsequent HWTHRQSTs to reflect the fact that one or more server identity errors were already encountered during an initial HWTHCONN or preceding HWTHRQST even in the case where the subsequent HWTHRQST did not experience the error.

The default value is HWTH_CERT_CHECK_SAN_ONLY.

HWTH_OPT_VERBOSE

A 4-byte integer optionally used to turn on verbose messaging to aid in the understanding of application logic or debugging of network configuration problems. Valid values are:

HWTH_VERBOSE_OFF

The toolkit produces no additional trace messages. Analysis of application results rely on the returnCode and diagArea values from the toolkit or other tracing outside of the toolkit.

HWTH_VERBOSE_ON

The toolkit produces redacted trace messages and directs them to the standard output for the application environment, unless directed elsewhere by the HWTH_OPT_VERBOSE_OUTPUT option.

Values associated with the following headers will be visible:

Headers
Accept
Accept-Charset
Accept-Encoding
Accept-Language
Accept-Ranges
Access-Control-Allow-Credentials
Access-Control-Allow-Headers
Access-Control-Allow-Methods
Access-Control-Allow-Origin
Access-Control-Expose-Headers
Access-Control-Max-Age
Access-Control-Request-Headers
Access-Control-Request-Method
Age
Allow
Cache-Control
Connection
Content-Encoding
Content-Language
Content-Length
Content-Location
Content-Range
Content-Type
Date
ETag
Expect
Expires
From
Host
Last-Modified
MIME-Version
Max-Forwards
Origin
Pragma
Proxy-Authenticate
Range
Referer
Retry-After
Server
TE
Trailer
Transfer-Encoding
Upgrade
User-Agent
Vary
Via
WWW-Authenticate
Warning

HWTH_VERBOSE_UNREDACTED

The toolkit produces trace messages and directs them to the standard output for the application environment, unless directed elsewhere by the HWTH_OPT_VERBOSE_OUTPUT option.

Default: HWTH_VERBOSE_OFF

HWTH_OPT_SSLTRACE

A fully qualified zFS file location for System SSL trace output. When specified, the trace environment variable GSK_TRACE is set to 255 (0xFF) and the variable GSK_TRACE_FILE is set to the user specified location passed in for this option. See Capturing trace data through environment variables in z/OS Cryptographic Services System SSL Programming for further details regarding usage of % in the file name for automatic inclusion of the process id and usage of gsktrace to format the resulting output.

Note: This option is only applicable when HWTH_SSL_USE is specified for HWTH_OPT_USE_SSL option. See AT-TLS usage overview for tracing options when AT-TLS is in effect.

HWTH_OPT_VERBOSE_OUTPUT

An optional 1- 8 character name of a valid DD (data definition) statement that specifies where trace debugging messages are to be routed. The toolkit only uses this option if the HWTH_OPT_VERBOSE option has been set to HWTH_VERBOSE_ON or HWTH_VERBOSE_UNREDACTED. The DD statement can specify one of the following destinations:

A pre-allocated, traditional z/OS® data set with the following recommended attributes:
- Physical sequential (DSORG=PS)
- Unblocked variable or undefined record format (RECFM=V or RECFM=U)
- Unspecified (or zero-valued) block size and record length, so that the default values will be set when the DD is opened
- Expandable (nonzero primary and secondary extents)
- Disposition of OLD (DISP=OLD), or NEW (DISP=NEW) if allocated in a DD statement in the same JCL job step that includes the EXEC for your toolkit application
A zFS file.

The toolkit automatically wraps the trace messages in the output data set or file when all available space has been consumed. When the wrap occurs, the toolkit clears the destination file or data set, and then writes an informational record that includes the time the wrap occurred.

For REXX only, dynamic allocation is not supported in System REXX using the TSO=NO option. If your REXX exec runs in System REXX environment and HWTH_OPT_VERBOSE_OUTPUT is desired, you must use the TSO=YES option.

Default: None. (Debugging messages are directed to the application's standard output.)

General options

Communication (socket) options

HWTH_OPT_PORT: An optional 4-byte integer indicating the remote port number to which to connect, instead of the default HTTP or HTTPS port.
HWTH_OPT_IPSTACK: An optional 1- 8 character local z/OS TCP/IP stack name to be used when communicating to the specified host name.
HWTH_OPT_LOCALIPADDR: An optional outgoing IP address from which the connection is to originate. This value should be in the same form as the HWTH_OPT_URI value for connections.
HWTH_OPT_LOCALPORT: An optional 4-byte integer indicating the outgoing port number from which the connection is to originate.
HWTH_OPT_SNDTIMEOUTVAL: An optional 4-byte integer to set a particular timeout value, in seconds, for the connection for outgoing requests.
Valid range: 1 - 2,678,400® seconds.
HWTH_OPT_RCVTIMEOUTVAL: An optional 4-byte integer to set a particular timeout value, in seconds, for the connection for incoming responses.
Valid range: 1 - 2,678,400 seconds.

Redirect options

HWTH_OPT_MAX_REDIRECTS

An optional 4-byte integer value that specifies the maximum number of redirects to follow (on a given request). If zero, redirects are not allowed by the application.

Valid range: 0 - 50

Default: 5

HWTH_OPT_XDOMAIN_REDIRECTS

An optional 4-byte integer value that specifies the cross-domain redirect behavior. This option is only effective when HWTH_OPT_MAX_REDIRECTS has a value greater than zero. Valid values are:

HWTH_XDOMAIN_REDIRS_NOTALLOWED: The toolkit will attempt to follow a redirect if the redirect targets the current domain of the connection associated with the request.
HWTH_XDOMAIN_REDIRS_ALLOWED: The toolkit attempts to follow a redirect even if the domain of the redirect is different from the current domain of the connection associated with the request.
Default: HWTH_XDOMAIN_REDIRS_NOTALLOWED

HWTH_OPT_REDIRECT_PROTOCOLS

An optional 4-byte integer value that specifies which additional protocols are allowed in the event that a redirect is received. Unlike many other options, calls to the set service that specify this option are cumulative. Multiple protocols can be specified by calling the set service multiple times, specifying one protocol at a time. This option is only effective when HWTH_OPT_MAX_REDIRECTS has a value greater than zero. Valid values are:

HWTH_REDIRECT_NOPROTCHANGE: Do not allow users to change protocols during a redirect. Effectively, this clears all prior set calls for this option and removes the default HWTH_REDIRECT_HTTPS as a valid redirect protocol.
HWTH_REDIRECT_HTTPS: Allow redirects to use the HTTPS protocol (SSL/TLS), even when the HWTH_OPT_USE_SSL value is set to HWTH_SSL_NONE. A protocol-changing redirect requiring a secure connection can occur only if either valid configuration information (such as HWTH_OPT_SSLKEYTYPE and other SSL support options) has been previously set by the application, or the connection has been transparently secured by AT-TLS.
HWTH_REDIRECT_HTTP: Allow redirects to use the HTTP protocol (non-SSL/TLS), even when the HWTH_OPT_USE_SSL value is set to HWTH_SSL_USE.
Note: Use this value carefully, as an SSL/TLS session can be downgraded to HTTP if this value is selected and a redirect to an HTTP host is requested.
HWTH_REDIRECT_NOHTTPS: Allow the user to override the default behavior of the toolkit and not allow redirects to use the HTTPS protocol.

Default: HWTH_REDIRECT_HTTPS

SSL/TLS support options

HWTH_OPT_USE_SSL

An optional 4-byte integer value that determines how SSL/TLS can be used to secure the connection. Valid values are:

HWTH_SSL_NONE

The application does not want to explicitly specify any SSL/TLS security configuration details to z/OS System SSL on the initial connection. This value should be selected when one of the following is true:

The HTTP protocol is the only protocol.
An HTTPS connection must be secured by AT-TLS.

Note: If redirects are enabled (and allowed), additional SSL/TLS configuration may be specified. In particular, a redirect to HTTPS will require either AT-TLS intervention or user supplied SSL/TLS options. For more information, see the HWTH_OPT_MAX_REDIRECTS option to enable redirects and the HWTH_OPT_REDIRECT_PROTOCOLS option to allow HTTPS.

HWTH_SSL_USE

The application wants to explicitly specify the SSL/TLS security configuration details to z/OS System SSL on the initial connection. This value should be selected only when the applications requires an HTTPS connection and there is no AT-TLS enabled policy for this connection that would upgrade the connection automatically. If this option is specified, and there is an AT-TLS enabled policy for this connection, the request will fail with an HWTH_COMMUNICATION_ERROR.

Note: SSL/TLS will always be used when connecting to the user-specified URI. A redirect URI could use the HTTP protocol only if redirects have been enabled (see the HWTH_OPT_MAX_REDIRECTS option for more information) and the HWTH_OPT_REDIRECT_PROTOCOLS option allows HTTP.

Default: HWTH_SSL_NONE

HWTH_OPT_SSLVERSION

An optional 4-byte integer value that sets one or more SSL versions to be supported by this HTTP request. Unlike many other options, calls to the set service that specify this option are cumulative. Multiple versions can be specified by calling the set service multiple times, setting one SSL version at a time. Valid values are:

HWTH_SSLVERSION_TLSv13: Support TLS version 1.3.
HWTH_SSLVERSION_TLSv12: Support TLS version 1.2.
HWTH_SSLVERSION_TLSv11: Support TLS version 1.1.
HWTH_SSLVERSION_TLSv1: Support TLS version 1.0.
HWTH_SSLVERSION_SSLv3: Support SSL version 3.0. This is not recommended.
HWTH_SSLVERSION_DEFAULT: SSL is to be used but no security versions are sent on the request. The default SSL versions as determined by z/OS is sent. This option can also be used to reset all SSL version values after disconnecting, before reusing an existing connection handle.

Default: HWTH_SSLVERSION_DEFAULT

HWTH_OPT_SSLKEYTYPE

An optional 4-byte integer value that specifies the type of keystore to be used for HTTPS requests. This option is required when HWTH_OPT_USE_SSL is set to HWTH_SSL_USE. Valid values are:

HWTH_SSLKEYTYPE_KEYDBFILE: Use a key database file.
HWTH_SSLKEYTYPE_KEYRINGNAME: Use a SAF key ring name or a PKCS #11 token.

HWTH_OPT_SSLKEY

An optional buffer that specifies the name of the keystore to be used. This option is required when HWTH_OPT_USE_SSL is set to HWTH_SSL_USE. The value that you specify depends on the value of HWTH_OPT_SSLKEYTYPE, as follows:

When HWTH_OPT_SSLKEYTYPE is...	The valid value for HWTH_OPT_SSLKEY is...
HWTH_SSLKEYTYPE_KEYDBFILE	The path and file name of the key database file.
HWTH_SSLKEYTYPE_KEYRINGNAME	One of the following: A SAF key ring name, in the form `userid/keyring` A PKCS #11 token, in the form `TOKEN/token_name`

HWTH_OPT_SSLKEYSTASHFILE

Specifies the path and file name of the password stash file created by the System SSL gskkyman utility. This option is required when HWTH_OPT_USE_SSL is set to HWTH_SSL_USE and HWTH_SSLKEYTYPE is HWTH_SSLKEYTYPE_KEYDBFILE.

HWTH_OPT_SSLCLIENTAUTHLABEL

An optional label that represents a client certificate. If SSL client authentication is requested by the server, this option allows you to specify a client certificate other than the default client certificate to be used in the SSL handshake.

HWTH_OPT_SSLCIPHERSPECS

An optional string value that represents the specification of the cipher suites to be used by System SSL. This option is set to make System SSL aware of an alternate cipher set other than the default set to be used for the connection.

The value string must use only 4-character cipher suite definitions and should be ordered by preference of use. Valid values will always have a length that is an even multiple of 4 characters because every cipher specification must be provided in its full 4-character form. The toolkit does not validate the contents of the string. An example of a valid value for this option is 003500380039002F00320033.

This option requires the HWTH_OPT_USE_SSL option to be set to HWTH_SSL_USE, indicating that SSL-related parameters supplied by the application, rather than an AT-TLS policy, must be used in establishing the secure connection.

See z/OS Cryptographic Services System SSL Programming for more details.

Note: When a secure connection is established, the set of ciphers offered by the client to the server helps determine how data will be encrypted and decrypted.

System SSL allows an application to replace the default cipher set with an alternate specification. That specification is a string which concatenates 1 or more of these cipher suite definitions (without delimiters).

Ciphers are identified by 2-character or 4-character cipher suite definitions. Every 2-character definition has a corresponding 4-character equivalent (the reverse is not true).

Proxy options

For more information about using a proxy with the toolkit, see Using a proxy server in Syntax, linkage, and programming considerations.

HWTH_OPT_PROXY

An optional buffer that specifies the HTTP proxy to use. This value should be in the same form as the HWTH_OPT_URI value for connections.

HWTH_OPT_PROXYPORT

An optional 4-byte integer indicating the proxy port to which to connect. The option is required if you specify the HWTH_OPT_PROXY.

HWTH_OPT_PROXYAUTH

An optional 4-byte integer value that specifies the proxy authentication type to be used for all proxy requests on this connection. Valid values are:

HWTH_PROXYAUTH_NONE: No proxy authorization is used.
HWTH_PROXYAUTH_BASIC: Use basic proxy authentication. The user name and password, as specify by the HWTH_OPT_PROXYAUTH_USERNAME and HWTH_OPT_PROXYAUTH_PASSWORD options, are processed and sent to the proxy as prescribed by the Basic authentication format. See RFC 7617.

HWTH_OPT_PROXYAUTH_USERNAME

An optional buffer that contains the user name to be used as part of authorizing to a proxy that requires Basic authentication. This option is used in combination with the HWTH_OPT_PROXYAUTH and HWTH_OPT_PROXYAUTH_PASSWORD options, and is required when HWTH_OPT_PROXYAUTH is set to HWTH_PROXYAUTH_BASIC.

HWTH_OPT_PROXYAUTH_PASSWORD

An optional buffer that contains the password to be used as part of authorizing to a proxy that requires Basic authentication. This option is used in combination with the HWTH_OPT_PROXYAUTH and HWTH_OPT_PROXYAUTH_USERNAME options, and is required when HWTH_OPT_PROXYAUTH is set to HWTH_PROXYAUTH_BASIC.

Cookie options

HWTH_OPT_COOKIETYPE

An optional 4-byte integer value that specifies the cookie store engine behavior to be used. Unlike other options, this option takes effect immediately, even after the connection has been established. Valid values are:

HWTH_COOKIETYPE_NONE

Turns off cookie support.

Cookies set with the HWTH_OPT_COOKIE request option or cookies that are sent in the Cookie header as part of the HWTH_OPT_HTTPHEADERS option will be passed to the server, but will not be retained for future use.
If the toolkit cookie engine had been enabled previously, all cookies in the in-memory cookie store is deleted.

Non-REXX:

All cookies received in Set-Cookie response headers will be passed to the response header processor as specified by HWTH_OPT_RESPONSEHDR_EXIT, but will not be retained for future use by the toolkit.

REXX:

All cookies received in Set-Cookie response headers will be passed to the application in the REXX stem specified by the HWTH_OPT_RESPONSEHDR_USERDATA option.

HWTH_COOKIETYPE_SESSION

Causes the toolkit cookie engine to activate and to start saving and sending session cookies for this connection. The cookies will be only available to the application while the connection is active and will not persist after the connection has ended.

On each subsequent request, all eligible cookies that match the criteria specified by the cookie is propagated to the server. (An eligible cookie means a cookie that passes the expiration, domain, path, and secure filters).
The HWTH_OPT_COOKIE request option sends any user-specified cookies in addition to any eligible cookies sent by the cookie engine, but will they not be retained by the engine.
All cookies received in response headers will automatically be added as session cookies for this connection.
If the application provides its own Cookie header as part of the HWTH_OPT_HTTPHEADERS option, this header is used and the cookie engine will not send any eligible cookies. In this case, all cookies specified by the HWTH_OPT_COOKIE request option is also ignored.
The session cookies can be primed from an input cookie buffer by using the set services with the HWT_OPT_COOKIE_INPUT_BUFFER option.

HWTH_COOKIETYPE_PERSIST

Causes the toolkit to start saving persistent cookies for this connection. If the HWTH_OPT_COOKIE_OUTPUT_BUFFER option has been set, the cookies are written to the application’s output cookie buffer during connection disconnect processing. If HWTH_OPT_COOKIE_OUTPUT_BUFFER has not been set, this cookie type has the same behavior as HWTH_COOKIETYPE_SESSION.

On each subsequent request, all eligible cookies that match the criteria specified by the cookie is propagated to the server. (An eligible cookie means a cookie that passes the expiration, domain, path, and secure filters).
The HWTH_OPT_COOKIE request option sends any user-specified cookies in addition to any eligible cookies sent by the cookie engine, but they are not retained by the engine.
All cookies received in response headers is automatically added as persistent cookies for this connection.
If the application provides its own Cookie header as part of the HWTH_OPT_HTTPHEADERS option, this header is used and the cookie engine will not send any eligible cookies. In this case, all cookies specified by the HWTH_OPT_COOKIE request option is also ignored.
The persistent cookies can be primed from an input cookie buffer by using the set services with the HWTH_OPT_COOKIE_INPUT_BUFFER option.

HWTH_OPT_COOKIE_INPUT_BUFFER

Optionally specifies a buffer containing a saved copy of the toolkit’s cookie data store (cookie jar). This buffer can be used to prime the toolkit’s cookie store for a new connection. (A previous connection with a HWTH_OPT_COOKIETYPE of HWTH_COOKIETYPE_PERSIST was disconnected, resulting in the toolkit writing its cookie store to a user-provided buffer, as specified by HWTH_OPT_COOKIE_OUTPUT_BUFFER).

If you specify the same address for this option as for HWTH_OPT_COOKIE_OUTPUT_BUFFER and the HWTH_OPT_COOKIETYPE is set to HWTH_COOKIETYPE_PERSIST, the input buffer is overlaid.
This parameter is ignored if HWTH_OPT_COOKIETYPE is set to HWTH_COOKIETYPE_NONE.
If you are setting this option using the REXX API, the options specify the REXX variable containing prior output from a cookie output buffer.

HWTH_OPT_COOKIE_OUTPUT_BUFFER

Optionally specifies a buffer for cookies to be saved when a connection is disconnected and the HWTH_OPT_COOKIETYPE is set to HWTH_COOKIETYPE_PERSIST.

If you specify the same address for this option as for HWTH_OPT_COOKIE_INPUT_BUFFER and the HWTH_OPT_COOKIETYPE is set to HWTH_COOKIETYPE_PERSIST, the input buffer is overlaid.
This parameter is ignored if HWTH_OPT_COOKIETYPE is not set to HWTH_COOKIETYPE_PERSIST.
If you are setting this option using the REXX API, the option specifies a REXX variable where the cookies are returned after a disconnect.

Guideline: The output buffer (cookie jar) specified here must be large enough to hold the cookies plus the metadata information about each cookie that is maintained by the cookie engine. Depending on how many cookies you plan to receive from the server (current maximum is 100), use the following formula to compute the size needed for the output buffer:

number_of_cookies × (average_cookie_data_size + 1K)

For instance, if the application is to hold 100 cookies with a maximum cookie size of 4 K bytes per cookie, the length of the output buffer would be: 100 × (4 K + 1 K) = 500K