TLS Connector Options

TLS connector options can be specified in connection profiles defined in [NET_SETTINGS], or in the default connection profile set with USYS$TLS_PARAMS in [DRIVER_SETTINGS].

For a named TLS connection profile:

[NET_SETTINGS]
ConnectionProfile{=}Option=Value{,Option=Value}

For example: 

[NET_SETTINGS]
 PSKProfile = shared_key=V6ry Secret Phrase!
 CertProfile = verify_server=yes,srv_cert=usys:myserver1.crt,srv_key=usys:myserver1.key

For connections that do not specify a connection profile, or for which the named profile is not defined:

[DRIVER_SETTINGS]
USYS$TLS_PARAMS{=}Option=Value{,Option=Value}

For example: 

[DRIVER_SETTINGS]
 USYS$TLS_PARAMS shared_key=V6ry Secret!

Options for Pre-Shared Key Authentication

Description

When specifying options with an equals (=) sign, there must be no spaces surrounding the = sign, otherwise an error is returned. Thus, shared_key=My Secret Key, not shared_key = My Secret Key.

Use commas to separate multiple options. Leading and trailing spaces before or after the comma are removed, but embedded spaces, for example in a shared key or password, are honored.

Note:  Because the options are comma separated, commas must not be used in option values.

For example, the following assignment: 

USYS$TLS_PARAMS shared_key=My Secret Key , verify_server=no

is treated as the following (leading and trailing spaces removed): 

USYS$TLS_PARAMS shared_key=My Secret Key, verify_server=no

and not as the following (with embedded spaces also removed):

USYS$TLS_PARAMS shared_key=MySecretKey, verify_server=no

Error Handling

When configuring the TLS connector, a mistake in the way connector options are specified could result in a lower level of security. For this reason, error handling is more strict. If an error is encountered, the following error is reported and processing stops.

Unknown, illegal or duplicate option specified in USYS$TLS_PARAMS: Option
 8061 - Network error detected ( (0)).

Some options specifying files have default values. These values can be re-assigned using the [FILES] section of the assignment file. If a default file does not exist, this may generate an error if the option is required.

For each option:

  • A name, an equals sign, and a value must be present
  • The name must be a recognized option, and is case insensitive
  • An option may only appear once
  • Where a value requires an option in a pre-defined set, that will be verified
  • Where a value specifies a file, the existence of the file will be verified
  • Commas are not allowed in values
  • Quotes are seen as part of the name or value including in file/path values
  • White space is allowed around the equals sign and the comma separator
  • Names and values are trimmed of leading and trailing spaces
  • A comma or end-of-line terminates an option

Passwords for Key Files

Key files for certificates may be password protected. If this is the case, the password should be provided using server_key_password or client_key_password options.

For example, if a server certificate and a password-protected key are in the same file, specify the key password using server_key_password.

Related Topics