oxmox
7063e2102e
git-subtree-dir: external/nng git-subtree-split: 29b73962b939a6fbbf6ea8d5d7680bb06d0eeb99
144 lines
5.3 KiB
Text
144 lines
5.3 KiB
Text
= nng_tls(7)
|
|
//
|
|
// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
|
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
|
//
|
|
// 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 - TLS transport
|
|
|
|
== SYNOPSIS
|
|
|
|
[source,c]
|
|
----
|
|
#include <nng/transport/tls/tls.h>
|
|
|
|
int nng_tls_register(void);
|
|
----
|
|
|
|
== DESCRIPTION
|
|
|
|
(((TLS)))(((Transport Layer Security)))(((transport, _tls_)))
|
|
The ((_tls_ transport)) provides communication support between
|
|
peers across a TCP/IP network using
|
|
https://tools.ietf.org/html/rfc5246[TLS v1.2] on top of
|
|
https://tools.ietf.org/html/rfc793[TCP].
|
|
Both IPv4 and IPv6 are supported when the underlying platform also supports it.
|
|
|
|
The protocol details are documented in
|
|
http://nanomsg.org/rfcs/sp-tls-v1.html[TLS Mapping for Scalability Protocols].
|
|
|
|
=== Registration
|
|
|
|
Depending upon how the library was built, it may be necessary to
|
|
register the transport by calling
|
|
xref:nng_tls_register.3.adoc[`nng_tls_register()`].
|
|
|
|
=== Availability
|
|
|
|
The _tls_ transport depends on the use of an external library.
|
|
As of this writing, https://tls.mbed.org/[mbedTLS] version 2.0
|
|
or later is required.
|
|
|
|
TIP: Applications may need to add this library (or libraries) to
|
|
their link line, particularly when using a statically built
|
|
library.
|
|
|
|
NOTE: The mbedTLS library uses different licensing terms than
|
|
_NNG_ itself; as of this writing it is offered under either
|
|
https://opensource.org/licenses/Apache-2.0[Apache License 2.0] or
|
|
https://opensource.org/licenses/gpl-license[GNU GPL] terms.
|
|
You are responsible for understanding and adhering to the
|
|
license terms of any libraries you use.
|
|
|
|
=== URI Format
|
|
|
|
(((URI, `tls+tcp://`)))
|
|
This transport uses URIs using the scheme `tls+tcp://`, followed by
|
|
an IP address or hostname, followed by a colon and finally a
|
|
TCP port number.
|
|
For example, to contact port 4433 on the localhost
|
|
either of the following URIs could be used: `tls+tcp://127.0.0.1:4433` or
|
|
`tls+tcp://localhost:4433`.
|
|
|
|
A URI may be restricted to IPv6 using the scheme `tls+tcp6://`, and may
|
|
be restricted to IPv4 using the scheme `tls+tcp4://`.
|
|
|
|
NOTE: Specifying `tls+tcp6://` may not prevent IPv4 hosts from being used with
|
|
IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with
|
|
listeners.
|
|
The details of this varies across operating systems.
|
|
|
|
NOTE: Both `tls+tcp6://` and `tls+tcp4://` are specific to _NNG_, and may not
|
|
be understood by other implementations.
|
|
|
|
TIP: We recommend using either numeric IP addresses, or names that are
|
|
specific to either IPv4 or IPv6 to prevent confusion and surprises.
|
|
|
|
When specifying IPv6 addresses, the address must be enclosed in
|
|
square brackets (`[]`) to avoid confusion with the final colon
|
|
separating the port.
|
|
|
|
For example, the same port 4433 on the IPv6 loopback address ('::1') would
|
|
be specified as `tls+tcp://[::1]:4433`.
|
|
|
|
TIP: Certificate validation generally works when using names
|
|
rather than IP addresses.
|
|
This transport automatically uses the name supplied in the URL when validating
|
|
the certificate supplied by the server.
|
|
|
|
The special value of 0 (`INADDR_ANY`) can be used for a listener
|
|
to indicate that it should listen on all interfaces on the host.
|
|
A short-hand for this form is to either omit the address, or specify
|
|
the asterisk (`*`) character.
|
|
For example, the following three URIs are all equivalent,
|
|
and could be used to listen to port 9999 on the host:
|
|
|
|
1. `tls+tcp://0.0.0.0:9999`
|
|
2. `tls+tcp://*:9999`
|
|
3. `tls+tcp://:9999`
|
|
|
|
The entire URI must be less than `NNG_MAXADDRLEN` bytes long.
|
|
|
|
=== Socket Address
|
|
|
|
When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure,
|
|
the actual structure is either of type
|
|
xref:nng_sockaddr_in.5.adoc[`nng_sockaddr_in`] (for IPv4) or
|
|
xref:nng_sockaddr_in6.5.adoc[`nng_sockaddr_in6`] (for IPv6).
|
|
|
|
=== Transport Options
|
|
|
|
The following transport options are available.
|
|
Note that setting these must be done before the transport is started.
|
|
|
|
* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`]
|
|
* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`]
|
|
* xref:nng_tcp_options.5.adoc#NNG_OPT_TCP_KEEPALIVE[`NNG_OPT_TCP_KEEPALIVE`]
|
|
* xref:nng_tcp_options.5.adoc#NNG_OPT_TCP_NODELAY[`NNG_OPT_TCP_NODELAY`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_AUTH_MODE[`NNG_OPT_TLS_AUTH_MODE`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_CA_FILE[`NNG_OPT_TLS_CA_FILE`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_CERT_KEY_FILE[`NNG_OPT_TLS_CERT_KEY_FILE`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_CONFIG[`NNG_OPT_TLS_CONFIG`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_VERIFIED[`NNG_OPT_TLS_VERIFIED_`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_PEER_CN[`NNG_OPT_TLS_PEER_CN`]
|
|
* xref:nng_tls_options.5.adoc#NNG_OPT_TLS_PEER_ALT_NAMES[`NNG_OPT_TLS_PEER_ALT_NAMES`]
|
|
* xref:nng_options.5.adoc#NNG_OPT_URL[`NNG_OPT_URL`]
|
|
|
|
== SEE ALSO
|
|
|
|
[.text-left]
|
|
xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)]
|
|
xref:nng_options.5.adoc[nng_options(5)],
|
|
xref:nng_sockaddr_in.5.adoc[nng_sockaddr_in(5)],
|
|
xref:nng_sockaddr_in6.5.adoc[nng_sockaddr_in6(5)],
|
|
xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
|
|
xref:nng_tls_config.5.adoc[nng_tls_config(5)],
|
|
xref:nng_tls_options.5.adoc[nng_tls_options(5)],
|
|
xref:nng.7.adoc[nng(7)],
|