= nng_tls_config_version(3tls)
//
// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_tls_config_version - configure TLS version

== SYNOPSIS

[source,c]
----
#include <nng/nng.h>
#include <nng/supplemental/tls/tls.h>

typedef enum nng_tls_version {
    NNG_TLS_1_2 = 0x303,
    NNG_TLS_1_3 = 0x304
} nng_tls_version;

int nng_tls_config_version(nng_tls_config *cfg, nng_tls_version min, nng_tls_version max);
----

== DESCRIPTION

The `nng_tls_config_version()` function configures the TLS version numbers that may be used when establishing TLS sessions using this configuration object.

The actual set supported range will further be restricted by the versions that the
xref:nng_tls_engine.5.adoc[TLS engine] supports.
If the TLS engine cannot support any TLS version in the requested range, then `NNG_ENOTSUP` is returned.

By default (if this function is not called), NNG will attempt to use both TLS v1.2 and TLS v1.3, provided that the TLS engine supports them.

Clients and servers will generally negotiate for the highest mutually supported TLS version.

== CAVEATS

* SSL v2.0, SSL v3.0, TLS v1.0 and TLS v1.1 are insecure, and not supported in NNG.

* Some TLS engines may not support limiting the maximum version.

* TLS v1.3 Zero Round Trip Time (0-RTT) is not supported in NNG.

* Session resumption is not supported in NNG (for any TLS version).

* TLS PSK support is dependent upon the engine.

== RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

== ERRORS

[horizontal]
`NNG_EINVAL`:: An invalid version was specified.
`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified.
`NNG_ENOTSUP`:: The TLS implementation cannot support any version in the requested range.

== SEE ALSO

[.text-left]
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)],
xref:nng_tls_engine.5.adoc[nng_tls_engine(5)],
xref:nng.7.adoc[nng(7)]
