fixes #186 Suggested API changes for nng TLS certs

7 files changed, 35 insertions, 263 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index a0d42874..d232dfe3 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -4,7 +4,7 @@ libnng(3)
 :manmanual: nng
 :mansource: nng
 :icons: font
-:copyright: Copyright 2018 Garrett D'Amore <garrett@damore.org> \
+: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 \
@@ -163,12 +163,9 @@ The following functions are used to manipulate TLS configuration objects.
 |===
 | <<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_cert#,nng_tls_config_ca_cert(3)>>|set certificate authority chain
-| <<nng_tls_config_cert#nng_tls_config_cert(3)>>|set own certificate
-| <<nng_tls_config_crl#nng_tls_config_crl(3)>>|set certificate revocation list
+| <<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_free#,nng_tls_config_free(3)>>}free TLS configuration
-| <<nng_tls_config_key#,nng_tls_config_key(3)>>|set private key
-| <<nng_tls_config_pass#nng_tls_config_pass(3)>>|set private key password
 | <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name
 |===
 
@@ -181,7 +178,6 @@ SEE ALSO
 COPYRIGHT
 ---------
 
-Copyright 2018 mailto:garrett@damore.org[Garrett D'Amore] +
 Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] +
 Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV]
 
diff --git a/docs/nng_tls.adoc b/docs/nng_tls.adoc
index 7c7be533..404923aa 100644
--- a/docs/nng_tls.adoc
+++ b/docs/nng_tls.adoc
@@ -167,68 +167,6 @@ care must be taken not to access it after the endpoint is closed.)
 Note that configuration object is not modifiable once it has been
 used in a running TLS stream.
 
-`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:
-+
-[cols="1,2"]
-|===
-
-| `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).
-+
-TIP: 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
diff --git a/docs/nng_tls_config_alloc.adoc b/docs/nng_tls_config_alloc.adoc
index 21b4755f..a5823e65 100644
--- a/docs/nng_tls_config_alloc.adoc
+++ b/docs/nng_tls_config_alloc.adoc
@@ -74,12 +74,9 @@ SEE ALSO
 
 <<nng_strerror#,nng_strerror(3)>>,
 <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>,
-<<nng_tls_config_ca_cert#,nng_tls_config_ca_cert(3)>>,
-<<nng_tls_config_cert#,nng_tls_config_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_own_cert#,nng_tls_config_own_cert(3)>>,
 <<nng_tls_config_free#,nng_tls_config_free(3)>>,
-<<nng_tls_config_key#,nng_tls_config_key(3)>>,
-<<nng_tls_config_pass#,nng_tls_config_pass(3)>>,
 <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>,
 <<nng#,nng(7)>>
 
diff --git a/docs/nng_tls_config_ca_cert.adoc b/docs/nng_tls_config_ca_chain.adoc
index 26700139..2888c032 100644
--- a/docs/nng_tls_config_ca_cert.adoc
+++ b/docs/nng_tls_config_ca_chain.adoc
@@ -1,5 +1,5 @@
-nng_tls_config_ca_cert(3)
-=========================
+nng_tls_config_ca_chain(3)
+==========================
 :doctype: manpage
 :manmanual: nng
 :mansource: nng
@@ -15,7 +15,7 @@ nng_tls_config_ca_cert(3)
 
 NAME
 ----
-nng_tls_config_ca_cert - configure certificate authority certificate chain
+nng_tls_config_ca_chain - configure certificate authority certificate chain
 
 SYNOPSIS
 --------
@@ -24,13 +24,14 @@ SYNOPSIS
 -----------
 #include <nng/nng.h>
 
-int nng_tls_config_ca_cert(nni_tls_config *cfg, const uint8_t *chain, size_t size)
+int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain,
+    const char *crl)
 -----------
 
 DESCRIPTION
 -----------
 
-The `nng_tls_config_ca_cert()` function configures a certificate or
+The `nng_tls_config_ca_chain()` function configures a certificate or
 certificate chain to be used when validating peers using the configuragion
 'cfg'.
 
@@ -41,15 +42,13 @@ no effect if the authentication mode is `NNG_TLS_AUTH_MODE_NONE`.
 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' may be in either
-https://tools.ietf.org/html/rfc7468[PEM] or DER format.  When the 'chain' is
-in PEM format, the certificates will be ASCII encoded, and concatenated
-together.  In this case the value of 'size' will be length of the
-corresponding string (without any terminating NUL byte).
-
-When using DER encoding, the 'size' will be the total number of bytes, after
-encoding.
+The certificates located in 'chain' must be a NUL 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
+certificate revocation list for the associated authority.
 
 RETURN VALUES
 -------------
diff --git a/docs/nng_tls_config_key.adoc b/docs/nng_tls_config_key.adoc
deleted file mode 100644
index 69e33fea..00000000
--- a/docs/nng_tls_config_key.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-nng_tls_config_key(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_key - configure certificate authority certificate chain
-
-SYNOPSIS
---------
-
-[source, c]
------------
-#include <nng/nng.h>
-
-int nng_tls_config_key(nni_tls_config *cfg, const uint8_t *key, size_t size)
------------
-
-DESCRIPTION
------------
-
-The `nng_tls_config_key()` function configures a private  'key' to be used
-along with a certificate established with
-<<nng_tls_config_cert#,nng_tls_config_cert(3)>>, for the given configuration
-'cfg'.
-
-This function should be called immediately after `nng_tls_config_cert()`,
-with the appropriate private key.
-
-The 'key' may be in either https://tools.ietf.org/html/rfc7468[PEM] or DER
-format.  When the 'chain' is
-in PEM format, the key will be ASCII encoded. A certificate may be present
-as well.  The value of 'size' corresponds to the PEM encoding, not including
-any terminating NUL byte.
-
-When using DER encoding, the 'size' will be the total number of bytes, after
-encoding.
-
-The key material may be encrypted with a password, which can be supplied
-using the <<nng_tls_config_pass#,nng_tls_config_pass(3)>> function.
-
-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`:: An invalid 'key' or 'size' was supplied.
-
-SEE ALSO
---------
-
-<<nng_strerror#,nng_strerror(3)>>,
-<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
-<<nng_tls_config_cert#,nng_tls_config_cert(3)>>,
-<<nng_tls_config_pass#,nng_tls_config_pass(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.adoc b/docs/nng_tls_config_own_cert.adoc
index f0ae7351..485e44ca 100644
--- a/docs/nng_tls_config_cert.adoc
+++ b/docs/nng_tls_config_own_cert.adoc
@@ -1,5 +1,5 @@
-nng_tls_config_cert(3)
-======================
+nng_tls_config_own_cert(3)
+==========================
 :doctype: manpage
 :manmanual: nng
 :mansource: nng
@@ -15,7 +15,7 @@ nng_tls_config_cert(3)
 
 NAME
 ----
-nng_tls_config_cert - configure own certificate
+nng_tls_config_own_cert - configure own certificate and key
 
 SYNOPSIS
 --------
@@ -24,36 +24,31 @@ SYNOPSIS
 -----------
 #include <nng/nng.h>
 
-int nng_tls_config_cert(nni_tls_config *cfg, const uint8_t *cert, size_t size)
+int nng_tls_config_own_cert(nni_tls_config *cfg, const char *cert,
+    const char *key, const char *pass);
 -----------
 
 DESCRIPTION
 -----------
 
-The `nng_tls_config_cert()` function configures a certificate identifying
-the local side of a TLS connection used with 'cfg'.  The certificate may be
-a chain, with the bottom-most signer first and the root at the end.  The
+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).
 
-NOTE: The certificate supplied always contains public keying material.  In
-order to actually use this, a private key will have to be supplied as well,
-using the <<nng_tls_config_key#,nnt_tls_config_key(3)>> function.
+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.
 
-TIP: This function may be called multiple times, to add additional chains
-to a configuration, without affecting those added previously.
+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' may be in either
-https://tools.ietf.org/html/rfc7468[PEM] or DER format.
-
-When the 'cert' is
-in PEM format, the certificate will be ASCII encoded.  Additionally a private
-key may or may not be present as additional concatenated PEM data.  The
-value of 'size' is the length of the concatenated strings, without any
-terminating NUL byte.
-
-When using DER encoding, the 'size' will be the total number of bytes, after
-encoding.
+The certificate located in 'cert' and 'key' must be NUL terminated C
+strings containing
+https://tools.ietf.org/html/rfc7468[PEM] formatted material.
 
 RETURN VALUES
 -------------
@@ -72,7 +67,6 @@ SEE ALSO
 
 <<nng_strerror#,nng_strerror(3)>>,
 <<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
-<<nng_tls_config_key#,nng_tls_config_key(3)>>,
 <<nng#,nng(7)>>
 
 
diff --git a/docs/nng_tls_config_pass.adoc b/docs/nng_tls_config_pass.adoc
deleted file mode 100644
index ca6a17e2..00000000
--- a/docs/nng_tls_config_pass.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-nng_tls_config_pass(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_pass - configure private key password
-
-SYNOPSIS
---------
-
-[source, c]
------------
-#include <nng/nng.h>
-
-int nng_tls_config_pass(nni_tls_config *cfg, const char *password)
------------
-
-DESCRIPTION
------------
-
-The `nng_tls_config_pass()` function configures 'password' used to decrypt
-a private key previously configured on the configuration 'cfg' with
-<<nng_tls_config_key#,nng_tls_config_key(3)>>.
-
-The 'password' is an ASCIIZ string.
-
-This function's affect is limited to decryption only the most recent
-private key that was configured.
-
-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`:: No private key was configured.
-
-SEE ALSO
---------
-
-<<nng_strerror#,nng_strerror(3)>>,
-<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
-<<nng_tls_config_key#,nng_tls_config_key(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].