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
#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:
Additionally, the values
TLS_PROTOCOL_TLSv1 (TLSv1.0, TLSv1.1 and TLSv1.2),
TLS_PROTOCOLS_ALL (all supported protocols) and
TLS_PROTOCOLS_DEFAULT (TLSv1.2 only) 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.0, tlsv1.1, tlsv1.2, all (all supported
protocols), default (an alias for secure), legacy (an alias for all) and
secure (currently TLSv1.2 only). 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:
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"
and "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())