diff options
Diffstat (limited to 'docs/man/nng_tls.adoc')
| -rw-r--r-- | docs/man/nng_tls.adoc | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/docs/man/nng_tls.adoc b/docs/man/nng_tls.adoc new file mode 100644 index 00000000..6ad4033f --- /dev/null +++ b/docs/man/nng_tls.adoc @@ -0,0 +1,180 @@ += nng_tls(7) +// +// Copyright 2018 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 for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/tls/tls.h> + +int nng_tls_register(void); +---------- + +== DESCRIPTION + +The _nng_tls_ transport provides communication support between +_nng_ sockets 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 `nng_tls_register`. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason. + +=== Availability + +The _tls_ transport depends on the use of an external library. +As of this writing, https://tls.mbed.org/[mbed TLS] 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 +_nng_ library. + +NOTE: The mbed TLS 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 make use of. + +=== URI Format + +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`. + +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`. + +NOTE: When using symbolic names, the name is resolved when the +name is first used. _nng_ won't become aware of changes in the +name resolution until restart, +usually.footnote:[This is a bug and will likely be fixed in the future.] + +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 `nng_sockaddr` structure, the actual structure is either +of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6). +These are `struct` types with the following definitions: + +[source,c] +-------- +#define NNG_AF_INET 3 <1> +#define NNG_AF_INET6 4 +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET + uint16_t sa_port; // TCP port number + uint32_t sa_addr; + // ... +} nng_sockaddr_in; + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET6 + uint16_t sa_port; // TCP port number + uint8_t sa_addr[16]; + // ... +} nng_sockaddr_in6; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`. +The `sa_port` and `sa_addr` are the TCP port number and address, both in +network byte order (most significant byte is first). + +=== Transport Options + +The following transport options are available. Note that +setting these must be done before the transport is started. + +`NNG_OPT_TLS_CONFIG`:: + +This option is used on an endpoint to access the underlying TLS +configuration object. The value is of type `nng_tls_config *`. + +TIP: Use this option when advanced TLS configuration is required. + +`NNG_OPT_TLS_CA_FILE`:: + +This is a write-only option used to load certificates associated +associated private key from a file. +See <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>> for more +information. + +`NNG_OPT_TLS_CERT_KEY_FILE`:: + +This is a write-only option used to load the local certificate and +associated private key from a file. The private key used must be +unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying +TLS configuration if more advanced configuration is needed.) +See <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>> for more +information. + +`NNG_OPT_TLS_AUTH_MODE`:: + +This is a write-only option used to configure the authentication mode +used. It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`, +`NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`. See +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>> for more details. + +`NNG_OPT_TLS_VERIFIED`:: + +This is a read-only option which returns a boolean value (integer 0 or 1). +It will true (1) if the remote peer has been properly verified using TLS +authentication, or false (0) otherwise. This option may return incorrect +results if peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>> |