Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
TLS_CONFIG_SET_PROTOCOLS(3) Library Functions ManuaTLS_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
       #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 con-
       figuration options apply	to both	clients	and servers, unless noted oth-
       erwise.

       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()	 func-
       tion.   The  protocol string is a comma or colon	separated list of key-
       words.  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 prefer-
       ence.

       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  se-
       lected 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	 pref-
       erence.	 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 ci-
       pher list when selecting	a cipher suite (server only).  This is consid-
       ered to be less secure than preferring the server's list.

       tls_config_prefer_ciphers_server() prefers ciphers in the server's  ci-
       pher list when selecting	a cipher suite (server only).  This is consid-
       ered to be more secure than preferring the client's list	and is the de-
       fault.

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())

FreeBSD	Ports 14.quarterly	 July 2, 2023	   TLS_CONFIG_SET_PROTOCOLS(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=tls_config_parse_protocols&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help