diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libnng.adoc | 8 | ||||
| -rw-r--r-- | docs/nng_tls_config_auth_mode.adoc | 4 | ||||
| -rw-r--r-- | docs/nng_tls_config_ca_chain.adoc | 12 | ||||
| -rw-r--r-- | docs/nng_tls_config_ca_file.adoc | 78 | ||||
| -rw-r--r-- | docs/nng_tls_config_cert_key_file.adoc | 83 | ||||
| -rw-r--r-- | docs/nng_tls_config_own_cert.adoc | 1 | ||||
| -rw-r--r-- | docs/nng_ws.adoc | 42 |
7 files changed, 207 insertions, 21 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc index d232dfe3..e5fd24ec 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -161,10 +161,12 @@ The following functions are used to manipulate TLS configuration objects. [cols="1,4"] |=== -| <<nng_tls_config_auth_alloc#nng_tls_config_alloc(3)>>|allocate TLS configuration -| <<nng_tls_config_auth_mode#nng_tls_config_auth_mode(3)>>|set authentication mode +| <<nng_tls_config_auth_alloc#,nng_tls_config_alloc(3)>>|allocate TLS configuration +| <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>|set authentication mode | <<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>|set certificate authority chain -| <<nng_tls_config_own_cert#nng_tls_config_own)cert(3)>>|set own certificate and key +| <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>|load certificate authority from file +| <<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file_cert(3)>>|load own certificate and key from file +| <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>|set own certificate and key | <<nng_tls_config_free#,nng_tls_config_free(3)>>}free TLS configuration | <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name |=== diff --git a/docs/nng_tls_config_auth_mode.adoc b/docs/nng_tls_config_auth_mode.adoc index fc4f9cfd..e07a6a41 100644 --- a/docs/nng_tls_config_auth_mode.adoc +++ b/docs/nng_tls_config_auth_mode.adoc @@ -73,8 +73,8 @@ SEE ALSO <<nng_strerror#,nng_strerror(3)>>, <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, -<<nng_tls_config_ca_cert#,nng_tls_config_ca_cert(3)>>, -<<nng_tls_config_crl#,nng_tls_config_crl(3)>>, +<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>, +<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>, <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>, <<nng#,nng(7)>> diff --git a/docs/nng_tls_config_ca_chain.adoc b/docs/nng_tls_config_ca_chain.adoc index 2888c032..dcf29a65 100644 --- a/docs/nng_tls_config_ca_chain.adoc +++ b/docs/nng_tls_config_ca_chain.adoc @@ -25,24 +25,23 @@ SYNOPSIS #include <nng/nng.h> int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain, - const char *crl) + const char *crl); ----------- DESCRIPTION ----------- The `nng_tls_config_ca_chain()` function configures a certificate or -certificate chain to be used when validating peers using the configuragion +certificate chain to be used when validating peers using the configuration 'cfg'. -NOTE: This function *must* be called when the TLS authentication mode SYNOPSIS -`NNG_TLS_AUTH_MODE_REQUIRED` or `NNG_TLS_AUTH_MODE_OPTIONAL`. It will have -no effect if the authentication mode is `NNG_TLS_AUTH_MODE_NONE`. +NOTE: Certificates *must* be configured when using the authentication mode +`NNG_TLS_AUTH_MODE_REQUIRED`. TIP: This function may be called multiple times, to add additional chains to a configuration, without affecting those added previously. -The certificates located in 'chain' must be a NUL terminated C string in +The certificates located in 'chain' must be a zero-terminated C string in https://tools.ietf.org/html/rfc7468[PEM] format. Multiple certificates may appear concatenated together, with the leaf certificate listed first. together. @@ -68,6 +67,7 @@ SEE ALSO <<nng_strerror#,nng_strerror(3)>>, <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>, +<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>, <<nng#,nng(7)>> diff --git a/docs/nng_tls_config_ca_file.adoc b/docs/nng_tls_config_ca_file.adoc new file mode 100644 index 00000000..32679fc1 --- /dev/null +++ b/docs/nng_tls_config_ca_file.adoc @@ -0,0 +1,78 @@ +nng_tls_config_ca_file(3) +========================= +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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_ca_file - load certificate authority from file + +SYNOPSIS +-------- + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_ca_file(nni_tls_config *cfg, const char *path); +----------- + +DESCRIPTION +----------- + +The `nng_tls_config_ca_file()` function configures the certificate authority +certificate chain and optional revocation list by loading the certificates +(and revocation list if present) from a single named file. The file must +at least one X.509 certificate in https://tools.ietf.org/html/rfc7468[PEM] +format, and may contain multiple such certificates, as well as zero or +more PEM CRL objects. This information is used to validate certificates +that are presented by peers, when using the configuration 'cfg'. + +NOTE: Certificates *must* be configured when using the authentication mode +`NNG_TLS_AUTH_MODE_REQUIRED`. + +TIP: This function may be called multiple times, to add additional chains +to a configuration, without affecting those added previously. + +RETURN VALUES +------------- + +This function returns 0 on success, and non-zero otherwise. + +ERRORS +------ + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration 'cfg' is already in use, and cannot be modified. +`NNG_EINVAL`:: The contents of 'path' are invalid or did not contain a valid PEM certificate. +`NNG_ENOENT`:: The file 'path' does not exist. +`NNG_EPERM`:: The file 'path' is not readable. + +SEE ALSO +-------- + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>, +<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>, +<<nng#,nng(7)>> + + +COPYRIGHT +--------- + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_tls_config_cert_key_file.adoc b/docs/nng_tls_config_cert_key_file.adoc new file mode 100644 index 00000000..9745d442 --- /dev/null +++ b/docs/nng_tls_config_cert_key_file.adoc @@ -0,0 +1,83 @@ +nng_tls_config_cert_key_file(3) +=============================== +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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_cert_key_file - load own certificate and key from file + +SYNOPSIS +-------- + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_cert_key_file(nni_tls_config *cfg, const char *path, + const char *pass); +----------- + +DESCRIPTION +----------- + +The `nng_tls_config_cert_key_file()` function loads a certificate (or +certificate chain) and a private key from the file named by 'path'. + +The file must contain both the https://tools.ietf.org/html/rfc7468[PEM] +encoded certificate and associated private key, which will be used when +establishing TLS sessions using 'cfg'. It may contain additional certificates +leading to a validation chain, with the leaf certificate first. +There is no need to include the self-signed root, as the peer +will need to have that already in order to perform it's own validation. + +The private key may be encrypted with a password, in which can be supplied in +'pass'. The value NULL should be supplied for 'pass' if the key is not +encrypted. + +On servers, it is possible to call this function multiple times for the +same configuration. This can be useful for specifying different parameters +to be used for different cryptographic algorithms. + + +RETURN VALUES +------------- + +This function returns 0 on success, and non-zero otherwise. + +ERRORS +------ + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration 'cfg' is already in use, and cannot be modified. +`NNG_EINVAL`:: The contents of 'path' are invalid. +`NNG_ENOENT`:: The file named by 'path' does not exist. +`NNG_EPERM`:: The file named by 'path' cannot be opened. + +SEE ALSO +-------- + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>, +<<nng#,nng(7)>> + + +COPYRIGHT +--------- + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_tls_config_own_cert.adoc b/docs/nng_tls_config_own_cert.adoc index 485e44ca..dd8f7362 100644 --- a/docs/nng_tls_config_own_cert.adoc +++ b/docs/nng_tls_config_own_cert.adoc @@ -67,6 +67,7 @@ SEE ALSO <<nng_strerror#,nng_strerror(3)>>, <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file(3)>>, <<nng#,nng(7)>> diff --git a/docs/nng_ws.adoc b/docs/nng_ws.adoc index 0afb417e..d36062ab 100644 --- a/docs/nng_ws.adoc +++ b/docs/nng_ws.adoc @@ -81,16 +81,12 @@ usually.footnote:[This is a bug and will likely be fixed in the future.] NOTE: The value specified as the host, if any, will also be used in the `Host:` HTTP header during HTTP negotiation. -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. `ws://0.0.0.0:9999` - 2. `ws://*:9999` - 3. `ws://:9999` +To listen to all ports on the system, the host name may be elided from +the URL on the listener. This will wind up listening to all interfaces +on the system, with possible caveats for IPv4 and IPv6 depending on what +the underlying system supports. (On most modern systems it will map to the +special IPv6 address `::`, and both IPv4 and IPv6 connections will be +permitted, with IPv4 addresses mapped to IPv6 addresses.) Socket Address ~~~~~~~~~~~~~~ @@ -159,6 +155,32 @@ the server is already running. Furthermore, attempts to modify the configuration object will fail if it is already in active use. This object is only available for `wss://` endpoints. +`NNG_OPT_WSS_TLS_CA_FILE`:: + +This is a write-only option used to load certificates associated +associated private key from a file. The value is a C string +containing the path name of the file. The file itself must contain +https://tools.ietf.org/html/rfc7468[PEM] format objects for one or more +X.509 certificates. It may also contain certificate revocation list (CRL) +objects well. Note that attempts to call this will fail if the +configuration associated with the underlying endpoint +is already in use. This option is only available for `wss://` endpoints. + +`NNG_OPT_WSS_TLS_CERT_KEY_FILE`:: + +This is a write-only option used to load the local certificate and +associated private key from a file. The value is a C string +containing the path name of the file. The file itself must contain PEM +format objects for the X.509 certificate and private key. Multiple +certificates may be listed in the file, to provide a validation chain, +with the leaf certificate listed first, and subsequent certificates listed +afterwards. Note that attempts to call this will fail if the +configuration associated with the underlying endpoint +is already in use. This option is only available for `wss://` endpoints. +The private key must not be encrypted. (Use the `NNG_OPT_WSS_TLS_CONFIG` +option to get the underlying TLS configuration if more advanced +configuration is needed.) + // We should also look at a hook mechanism for listeners. Probably this could // look like NNG_OPT_WS_LISTEN_HOOK_FUNC which would take a function pointer // along the lines of int hook(void *, char *req_headers, char **res_headers), |