Import LibreSSL 3.2.0

1 files changed, 197 insertions, 0 deletions

diff --git a/man/tls_config_set_protocols.3 b/man/tls_config_set_protocols.3
new file mode 100644
index 0000000..0aed5b9
--- /dev/null
+++ b/man/tls_config_set_protocols.3
@@ -0,0 +1,197 @@
+.\" $OpenBSD: tls_config_set_protocols.3,v 1.8 2020/01/22 06:46:34 beck Exp $
+.\"
+.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
+.\" Copyright (c) 2015, 2016 Joel Sing <jsing@openbsd.org>
+.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: January 22 2020 $
+.Dt TLS_CONFIG_SET_PROTOCOLS 3
+.Os
+.Sh NAME
+.Nm tls_config_set_protocols ,
+.Nm tls_config_parse_protocols ,
+.Nm tls_config_set_alpn ,
+.Nm tls_config_set_ciphers ,
+.Nm tls_config_set_dheparams ,
+.Nm tls_config_set_ecdhecurves ,
+.Nm tls_config_prefer_ciphers_client ,
+.Nm tls_config_prefer_ciphers_server
+.Nd TLS protocol and cipher selection
+.Sh SYNOPSIS
+.In tls.h
+.Ft int
+.Fo tls_config_set_protocols
+.Fa "struct tls_config *config"
+.Fa "uint32_t protocols"
+.Fc
+.Ft int
+.Fo tls_config_parse_protocols
+.Fa "uint32_t *protocols"
+.Fa "const char *protostr"
+.Fc
+.Ft int
+.Fo tls_config_set_alpn
+.Fa "struct tls_config *config"
+.Fa "const char *alpn"
+.Fc
+.Ft int
+.Fo tls_config_set_ciphers
+.Fa "struct tls_config *config"
+.Fa "const char *ciphers"
+.Fc
+.Ft int
+.Fo tls_config_set_dheparams
+.Fa "struct tls_config *config"
+.Fa "const char *params"
+.Fc
+.Ft int
+.Fo tls_config_set_ecdhecurves
+.Fa "struct tls_config *config"
+.Fa "const char *curves"
+.Fc
+.Ft void
+.Fn tls_config_prefer_ciphers_client "struct tls_config *config"
+.Ft void
+.Fn tls_config_prefer_ciphers_server "struct tls_config *config"
+.Sh DESCRIPTION
+These functions modify a configuration by setting parameters.
+The configuration options apply to both clients and servers, unless noted
+otherwise.
+.Pp
+.Fn tls_config_set_protocols
+specifies which versions of the TLS protocol may be used.
+Possible values are the bitwise OR of:
+.Pp
+.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact
+.It Dv TLS_PROTOCOL_TLSv1_0
+.It Dv TLS_PROTOCOL_TLSv1_1
+.It Dv TLS_PROTOCOL_TLSv1_2
+.It Dv TLS_PROTOCOL_TLSv1_3
+.El
+.Pp
+Additionally, the values
+.Dv TLS_PROTOCOL_TLSv1
+(TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3),
+.Dv TLS_PROTOCOLS_ALL
+(all supported protocols) and
+.Dv TLS_PROTOCOLS_DEFAULT
+(TLSv1.2 and TLSv1.3) may be used.
+.Pp
+The
+.Fn tls_config_parse_protocols
+utility function parses a protocol string and returns the corresponding
+value via the
+.Ar protocols
+argument.
+This value can then be passed to the
+.Fn 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, tlsv1.3, all (all supported
+protocols), default (an alias for secure), legacy (an alias for all) and
+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.
+.Pp
+.Fn 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.
+.Pp
+.Fn 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:
+.Pp
+.Bl -tag -width "insecure" -offset indent -compact
+.It Dv "secure" (or alias "default")
+.It Dv "compat"
+.It Dv "legacy"
+.It Dv "insecure" (or alias "all")
+.El
+.Pp
+Alternatively, libssl cipher strings can be specified.
+See the CIPHERS section of
+.Xr openssl 1
+for further information.
+.Pp
+.Fn 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.
+.Pp
+.Fn 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
+.Fn tls_config_set_ecdhecurve ,
+which is deprecated.
+.Pp
+.Fn 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.
+.Pp
+.Fn 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.
+.Sh RETURN VALUES
+These functions return 0 on success or -1 on error.
+.Sh SEE ALSO
+.Xr tls_config_ocsp_require_stapling 3 ,
+.Xr tls_config_set_session_id 3 ,
+.Xr tls_config_verify 3 ,
+.Xr tls_init 3 ,
+.Xr tls_load_file 3
+.Sh HISTORY
+.Fn tls_config_set_ciphers
+appeared in
+.Ox 5.6
+and got its final name in
+.Ox 5.7 .
+.Pp
+.Fn tls_config_set_protocols ,
+.Fn tls_config_parse_protocols ,
+.Fn tls_config_set_dheparams ,
+and
+.Fn tls_config_set_ecdhecurve
+appeared in
+.Ox 5.7 ,
+.Fn tls_config_prefer_ciphers_client
+and
+.Fn tls_config_prefer_ciphers_server
+in
+.Ox 5.9 ,
+and
+.Fn tls_config_set_alpn
+in
+.Ox 6.1 .
+.Sh AUTHORS
+.An Joel Sing Aq Mt jsing@openbsd.org
+with contributions from
+.An Ted Unangst Aq Mt tedu@openbsd.org
+.Pq Fn tls_config_set_ciphers
+and
+.An Reyk Floeter Aq Mt reyk@openbsd.org
+.Pq Fn tls_config_set_ecdhecurve