From a245b3add629d081015b0f7223e978f000949aa8 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 15 Feb 2018 20:49:28 -0800 Subject: Minor markup fixes for TLS pages. --- docs/libnng.adoc | 1 - docs/nng_tls_config_alloc.adoc | 8 ++++---- docs/nng_tls_config_auth_mode.adoc | 4 ++-- docs/nng_tls_config_ca_chain.adoc | 10 +++++----- docs/nng_tls_config_ca_file.adoc | 10 +++++----- docs/nng_tls_config_cert_key_file.adoc | 14 +++++++------- docs/nng_tls_config_free.adoc | 2 +- docs/nng_tls_config_own_cert.adoc | 16 ++++++++-------- docs/nng_tls_config_server_name.adoc | 6 +++--- 9 files changed, 35 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/docs/libnng.adoc b/docs/libnng.adoc index 3612b658..2ce2732b 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -41,7 +41,6 @@ The following functions operate on sockets. |=== |<>|close a socket -|<>|close all open sockets |<>|create and start a dialer |<>|get a socket option |<>|create and start a listener diff --git a/docs/nng_tls_config_alloc.adoc b/docs/nng_tls_config_alloc.adoc index 98884f70..8e414fcc 100644 --- a/docs/nng_tls_config_alloc.adoc +++ b/docs/nng_tls_config_alloc.adoc @@ -32,11 +32,11 @@ int nng_tls_config_alloc(nni_tls_config **cfgp, nng_tls_mode mode); The `nng_tls_config_alloc()` function creates a newly initialized https://tools.ietf.org/html/rfc5246[Transport Layer Security]) configuration object, and stores a pointer to it in the value pointed -to by 'cfgp'. +to by _cfgp_. This object is initialized for use when acting as either a client (`NNG_TLS_MODE_CLIENT`) or as a server (`NNG_TLS_MODE_SERVER`), -depending on the value of 'mode'. +depending on the value of _mode_. A TLS object can be further modified by functions that set the security keys used, peeer certificates, protocol policies, and so forth. @@ -56,8 +56,8 @@ This function returns 0 on success, and non-zero otherwise. == ERRORS -`NNG_ENOMEM`:: Insufficient memory is available to allocate the object. -`NNG_EINVAL`:: An invalid 'mode' was specified. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EINVAL`:: An invalid _mode_ was specified. == SEE ALSO diff --git a/docs/nng_tls_config_auth_mode.adoc b/docs/nng_tls_config_auth_mode.adoc index 1895abba..3501167b 100644 --- a/docs/nng_tls_config_auth_mode.adoc +++ b/docs/nng_tls_config_auth_mode.adoc @@ -56,8 +56,8 @@ This function returns 0 on success, and non-zero otherwise. == ERRORS `NNG_ENOMEM`:: Insufficient memory is available. -`NNG_EINVAL`:: An invalid 'mode' was specified. -`NNG_EBUSY`:: The configuration 'cfg' is already in use, and cannot be modified. +`NNG_EINVAL`:: An invalid _mode_ was specified. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. == SEE ALSO diff --git a/docs/nng_tls_config_ca_chain.adoc b/docs/nng_tls_config_ca_chain.adoc index 19c97409..fc4621d9 100644 --- a/docs/nng_tls_config_ca_chain.adoc +++ b/docs/nng_tls_config_ca_chain.adoc @@ -27,7 +27,7 @@ int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain, The `nng_tls_config_ca_chain()` function configures a certificate or certificate chain to be used when validating peers using the configuration -'cfg'. +_cfg_. NOTE: Certificates *must* be configured when using the authentication mode `NNG_TLS_AUTH_MODE_REQUIRED`. @@ -35,12 +35,12 @@ NOTE: Certificates *must* be configured when using the authentication mode 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 zero-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. -The 'crl' may be NULL, or may also be a C string containing a PEM format +The _crl_ may be `NULL`, or may also be a C string containing a PEM format certificate revocation list for the associated authority. == RETURN VALUES @@ -50,8 +50,8 @@ 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`:: An invalid 'chain' or 'size' was supplied. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: An invalid _chain_ or _crl_ was supplied. == SEE ALSO diff --git a/docs/nng_tls_config_ca_file.adoc b/docs/nng_tls_config_ca_file.adoc index 0c8d9075..4fe5feb6 100644 --- a/docs/nng_tls_config_ca_file.adoc +++ b/docs/nng_tls_config_ca_file.adoc @@ -30,7 +30,7 @@ certificate chain and optional revocation list by loading the certificates 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'. +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`. @@ -45,10 +45,10 @@ 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. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: The contents of _path_ are invalid or do not contain a valid PEM certificate. +`NNG_ENOENT`:: The file _path_ does not exist. +`NNG_EPERM`:: The file _path_ is not readable. == SEE ALSO diff --git a/docs/nng_tls_config_cert_key_file.adoc b/docs/nng_tls_config_cert_key_file.adoc index 119e3939..47c49bbe 100644 --- a/docs/nng_tls_config_cert_key_file.adoc +++ b/docs/nng_tls_config_cert_key_file.adoc @@ -26,17 +26,17 @@ int nng_tls_config_cert_key_file(nni_tls_config *cfg, const char *path, == 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'. +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 +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 +_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 @@ -50,10 +50,10 @@ 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. +`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 diff --git a/docs/nng_tls_config_free.adoc b/docs/nng_tls_config_free.adoc index 823127fb..e3b2f29a 100644 --- a/docs/nng_tls_config_free.adoc +++ b/docs/nng_tls_config_free.adoc @@ -25,7 +25,7 @@ void nng_tls_config_free(nni_tls_config *cfg); == DESCRIPTION The `nng_tls_config_free()` decrements the reference count on the -TLS configuration object pointed to by 'cfg', and if the resulting +TLS configuration object pointed to by _cfg_, and if the resulting reference count is zero, then deallocates the configuration object. == RETURN VALUES diff --git a/docs/nng_tls_config_own_cert.adoc b/docs/nng_tls_config_own_cert.adoc index c43828cf..7741d698 100644 --- a/docs/nng_tls_config_own_cert.adoc +++ b/docs/nng_tls_config_own_cert.adoc @@ -25,22 +25,22 @@ int nng_tls_config_own_cert(nni_tls_config *cfg, const char *cert, == DESCRIPTION -The `nng_tls_config_own_cert()` function configures a certificate 'cert' -identifying the local side of a TLS connection used with 'cfg', along with an -associated private or secret key 'key'. The certificate may be +The `nng_tls_config_own_cert()` function configures a certificate _cert_ +identifying the local side of a TLS connection used with _cfg_, along with an +associated private or secret key _key_. The certificate may be a chain, with the leaf signer first and the root at the end. The self-signed certificate at the end can be omitted. (The client should already have it, and will have to in order to validate this certificate anyway). -The '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 +The _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. -The certificate located in 'cert' and 'key' must be NUL terminated C +The certificate located in _cert_ and _key_ must be NUL (`\0`) terminated C strings containing https://tools.ietf.org/html/rfc7468[PEM] formatted material. @@ -51,8 +51,8 @@ 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`:: An invalid 'cert' or 'size' was supplied. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: An invalid _cert_ or _key_ was supplied. == SEE ALSO diff --git a/docs/nng_tls_config_server_name.adoc b/docs/nng_tls_config_server_name.adoc index bbe017bb..1dc21e9c 100644 --- a/docs/nng_tls_config_server_name.adoc +++ b/docs/nng_tls_config_server_name.adoc @@ -25,9 +25,9 @@ int nng_tls_config_server_name(nni_tls_config *cfg, const char *name); == DESCRIPTION The `nng_tls_config_server_name()` function configures the remote server name -to be used by a client when connection to a server. The supplied 'name' +to be used by a client when connection to a server. The supplied _name_ is used when comparing the identity in the server's certificate. Furthermore, -when Server Name Indication (SNI) is used, the 'name' may be sent to the server +when Server Name Indication (SNI) is used, the _name_ may be sent to the server as a hint to tell it which of several possible certificates should be used. TIP: This function is only useful in configuring client behavior. @@ -39,7 +39,7 @@ 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_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. == SEE ALSO -- cgit v1.2.3-70-g09d2