NAME
tls_config_set_protocols
,
tls_config_parse_protocols
,
tls_config_set_alpn
,
tls_config_set_ciphers
,
tls_config_set_dheparams
,
tls_config_set_ecdhecurve
,
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_ecdhecurve
(struct
tls_config *config, const char *name);
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_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
())