From ee0bdc4423c74cb2004920b744c8bae379408cd2 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 21 Nov 2017 00:37:52 -0800 Subject: man page updates for 0.0.0 --- man/v0.0.0/nng_tls.html | 858 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 858 insertions(+) create mode 100644 man/v0.0.0/nng_tls.html (limited to 'man') diff --git a/man/v0.0.0/nng_tls.html b/man/v0.0.0/nng_tls.html new file mode 100644 index 00000000..767d07d9 --- /dev/null +++ b/man/v0.0.0/nng_tls.html @@ -0,0 +1,858 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_tls(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#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 +TLS v1.2 on top of +TCP. Both IPv4 and IPv6 +are supported when the underlying platform also supports it.

+
+
+

The protocol details are documented in +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, mbed TLS is required.

+
+
+ + + + + +
+ + +Applications may need to add this library (or libraries) to +their link line, particularly when using a statically built +nng library. +
+
+
+ + + + + +
+ + +The mbed TLS library uses different licensing terms than +nng itself; as of this writing it is offered under either +Apache License 2.0 or +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://, 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://127.0.0.1:4433 or +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 tcp://[::1]:4433.

+
+
+ + + + + +
+ + +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.[1] +
+
+
+ + + + + +
+ + +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://0.0.0.0:9999

    +
    2. +
  2. +

    tls://*:9999

    +
    3. +
  3. +

    tls://:9999

    +
    4. +
+
+
+

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:

+
+
+
+
#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;
+
+
+
+ + + + + + + + + +
1The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2Other 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).

+
+
+
+

X.509 Formats

+
+

The tls transport supports certificates and key material provided +in either PEM or DER encoding. When using PEM format data, the +encoding must be at the start of the data, with no intervening +content. Furthermore, PEM encoded objects may have a terminating +NUL byte, which will be ignored if present.

+
+
+
+

Transport Options

+
+

The following transport options are available. Note that +setting these must be done before the transport is started.

+
+
+
+
NNG_OPT_TLS_CA_CERT
+
+

This is a write-only binay object containing a certificate +chain, consisting of one or more X.509 certificates encoded in +either PEM or DER format. These certificates are used to +validate the peer. If multiple certificates are presented, +they must be in the same format.

+
+
NNG_OPT_TLS_CRL
+
+

This is a write-only CRL (revocation list) in X.509 format, +specifying certificates which may not be used.

+
+
NNG_OPT_TLS_CERT
+
+

This is an X.509 certificate containing the peers +own public credentials. For servers, this option may be supplied +multiple times, in order to specify multiple certificates +in order to offer different algorithms. Clients can only +have a single certificate.

+
+
NNG_OPT_TLS_PRIVATE_KEY
+
+

This is an encoded private key, corresponding to the most +recently established certificate.

+
+
NNG_OPT_TLS_PRIVATE_KEY_PASSWORD
+
+

This is a string (NUL byte terminated) used to decrypt the +most recently supplied private key, if the private key +is encrypted. (If the private key is not encrypted, then +this option need not be supplied.)

+
+
NNG_OPT_TLS_AUTH_MODE
+
+

This is a write only integer, indicating whether the +peer should be authenticated. It can take one of the +following values:

+ ++++ + + + + + + + + + + + + + + +

nng_tls_auth_mode_none

No authentication of the peer is performed.

nng_tls_auth_mode_optional

The peer certificate is checked if presented, but is not required to be valid or present.

nng_tls_auth_mode_required

The peer certificate must be present and valid.

+
+

The default is nng_tls_auth_mode_required for +clients (meaning the server must present a valid +certificate) and nng_tls_auth_mode_none for +servers (meaning any client may connect).

+
+
+ + + + + +
+ + +For TLS client authentication, set this to +nng_auth_mode_required and set the value +of NNG_OPT_TLS_CA_CERT to a certificate corresponding +to your own Certificate Authority. +
+
+
+
NNG_OPT_TLS_AUTH_VERIFIED
+
+

This is a read-only boolean option available only for +pipes, indicating whether the peer certificate was +valdiated or not. This is only set when the pipe +has completed the handshake with the peer (which always +occurs before exchanging data), and will only be set +if the NNG_OPT_TLS_AUTH_MODE option is set to +nng_tls_auth_mode_optional or nng_tls_auth_mode_required.

+
+
+
+
+
+
+
+

SEE ALSO

+
+
+

nng(7)

+
+
+
+
+

COPYRIGHT

+
+
+

Copyright 2017 Staysail Systems, Inc.
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+
+
+
+1. This is a bug and will likely be fixed in the future. +
+
+ + + -- cgit v1.2.3-70-g09d2