TLS_CONFIG_SET_PROTOCOLS(3) | Library Functions Manual | TLS_CONFIG_SET_PROTOCOLS(3)

# NAME

`tls_config_set_protocols`, `tls_config_parse_protocols`, `tls_config_set_alpn`, `tls_config_set_ciphers`, `tls_config_set_dheparams`, `tls_config_set_ecdhecurves`, `tls_config_prefer_ciphers_client`, `tls_config_prefer_ciphers_server` — TLS protocol and cipher selection

# SYNOPSIS

library “libtls” libssl libcrypto
`#include <tls.h>`

int
`tls_config_set_protocols`(struct tls_config *config, uint32_t protocols);

int
`tls_config_parse_protocols`(uint32_t *protocols, const char *protostr);

int
`tls_config_set_alpn`(struct tls_config *config, const char *alpn);

int
`tls_config_set_ciphers`(struct tls_config *config, const char *ciphers);

int
`tls_config_set_dheparams`(struct tls_config *config, const char *params);

int
`tls_config_set_ecdhecurves`(struct tls_config *config, const char *curves);

void
`tls_config_prefer_ciphers_client`(struct tls_config *config);

void
`tls_config_prefer_ciphers_server`(struct tls_config *config);

# DESCRIPTION

These functions modify a configuration by setting parameters. The configuration options apply to both clients and servers, unless noted otherwise.

`tls_config_set_protocols`() specifies which versions of the TLS protocol may be used. Possible values are the bitwise OR of:

- `TLS_PROTOCOL_TLSv1_2`
- `TLS_PROTOCOL_TLSv1_3`

Additionally, the values `TLS_PROTOCOL_TLSv1` (TLSv1.2, TLSv1.3), `TLS_PROTOCOLS_ALL` (all supported protocols) and `TLS_PROTOCOLS_DEFAULT` (TLSv1.2 and TLSv1.3) may be used.

The `tls_config_parse_protocols`() utility function parses a protocol string and returns the corresponding value via the protocols argument. This value can then be passed to the `tls_config_set_protocols`() function. The protocol string is a comma or colon separated list of keywords. Valid keywords are:

`tlsv1.2`
`tlsv1.3`
`all`
  (all supported protocols)
`default`
  (an alias for `secure`)
`legacy`
  (an alias for `all`)
`secure`
  (currently TLSv1.2 and TLSv1.3)

If a value has a negative prefix (in the form of a leading exclamation mark) then it is removed from the list of available protocols, rather than being added to it.

`tls_config_set_alpn`() sets the ALPN protocols that are supported. The alpn string is a comma separated list of protocols, in order of preference.

`tls_config_set_ciphers`() sets the list of ciphers that may be used. Lists of ciphers are specified by name, and the permitted names are:

- `secure` (or alias `default`)
- `compat`
- `legacy`
- `insecure` (or alias `all`)

Alternatively, libssl cipher strings can be specified. See the CIPHERS section of openssl(1) for further information.

`tls_config_set_dheparams`() specifies the parameters that will be used during Diffie-Hellman Ephemeral (DHE) key exchange. Possible values are:

- `none`
- `auto`
- `legacy`

In `auto` mode, the key size for the ephemeral key is automatically selected based on the size of the private key being used for signing. In `legacy` mode, 1024 bit ephemeral keys are used. The default value is `none`, which disables DHE key exchange.

`tls_config_set_ecdhecurves`() specifies the names of the elliptic curves that may be used during Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) key exchange. This is a comma separated list, given in order of preference. The special value of "default" will use the default curves (currently X25519, P-256 and P-384). This function replaces `tls_config_set_ecdhecurve`(), which is deprecated.

`tls_config_prefer_ciphers_client`() prefers ciphers in the client's cipher list when selecting a cipher suite (server only). This is considered to be less secure than preferring the server's list.

`tls_config_prefer_ciphers_server`() prefers ciphers in the server's cipher list when selecting a cipher suite (server only). This is considered to be more secure than preferring the client's list and is the default.

# RETURN VALUES

These functions return 0 on success or -1 on error.

# SEE ALSO

tls_config_ocsp_require_stapling(3), tls_config_set_session_id(3), tls_config_verify(3), tls_init(3), tls_load_file(3)

# HISTORY

`tls_config_set_ciphers`() appeared in OpenBSD 5.6 and got its final name in OpenBSD 5.7.

`tls_config_set_protocols`(), `tls_config_parse_protocols`(), `tls_config_set_dheparams`(), and `tls_config_set_ecdhecurve`() appeared in OpenBSD 5.7, `tls_config_prefer_ciphers_client`() and `tls_config_prefer_ciphers_server`() in OpenBSD 5.9, and `tls_config_set_alpn`() in OpenBSD 6.1.

# AUTHORS

Joel Sing <jsing@openbsd.org> with contributions from
Ted Unangst <tedu@openbsd.org> (`tls_config_set_ciphers`()) and
Reyk Floeter <reyk@openbsd.org> (`tls_config_set_ecdhecurve`())

July 7, 2025 | Debian