From 6dddc0bfcb79615b8be470a5e16918360d57cadb Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 9 Jan 2018 18:42:28 -0800 Subject: fixes #186 Suggested API changes for nng TLS certs --- docs/libnng.adoc | 10 ++--- docs/nng_tls.adoc | 62 ---------------------------- docs/nng_tls_config_alloc.adoc | 7 +--- docs/nng_tls_config_ca_cert.adoc | 82 ------------------------------------- docs/nng_tls_config_ca_chain.adoc | 81 ++++++++++++++++++++++++++++++++++++ docs/nng_tls_config_cert.adoc | 86 --------------------------------------- docs/nng_tls_config_key.adoc | 82 ------------------------------------- docs/nng_tls_config_own_cert.adoc | 80 ++++++++++++++++++++++++++++++++++++ docs/nng_tls_config_pass.adoc | 70 ------------------------------- 9 files changed, 166 insertions(+), 394 deletions(-) delete mode 100644 docs/nng_tls_config_ca_cert.adoc create mode 100644 docs/nng_tls_config_ca_chain.adoc delete mode 100644 docs/nng_tls_config_cert.adoc delete mode 100644 docs/nng_tls_config_key.adoc create mode 100644 docs/nng_tls_config_own_cert.adoc delete mode 100644 docs/nng_tls_config_pass.adoc (limited to 'docs') 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 \ +:copyright: Copyright 2018 Staysail Systems, Inc. \ Copyright 2018 Capitar IT Group BV \ 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. |=== | <>|allocate TLS configuration | <>|set authentication mode -| <>|set certificate authority chain -| <>|set own certificate -| <>|set certificate revocation list +| <>|set certificate authority chain +| <>|set own certificate and key | <>}free TLS configuration -| <>|set private key -| <>|set private key password | <>|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 <>, <>, -<>, -<>, -<>, +<>, +<>, <>, -<>, -<>, <>, <> diff --git a/docs/nng_tls_config_ca_cert.adoc b/docs/nng_tls_config_ca_cert.adoc deleted file mode 100644 index 26700139..00000000 --- a/docs/nng_tls_config_ca_cert.adoc +++ /dev/null @@ -1,82 +0,0 @@ -nng_tls_config_ca_cert(3) -========================= -:doctype: manpage -:manmanual: nng -:mansource: nng -:manvolnum: 3 -:icons: font -:source-highlighter: pygments -:copyright: Copyright 2018 Staysail Systems, Inc. \ - Copyright 2018 Capitar IT Group BV \ - 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_cert - configure certificate authority certificate chain - -SYNOPSIS --------- - -[source, c] ------------ -#include - -int nng_tls_config_ca_cert(nni_tls_config *cfg, const uint8_t *chain, size_t size) ------------ - -DESCRIPTION ------------ - -The `nng_tls_config_ca_cert()` function configures a certificate or -certificate chain to be used when validating peers using the configuragion -'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`. - -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. - - -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 'chain' or 'size' was supplied. - -SEE ALSO --------- - -<>, -<>, -<>, -<> - - -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_ca_chain.adoc b/docs/nng_tls_config_ca_chain.adoc new file mode 100644 index 00000000..2888c032 --- /dev/null +++ b/docs/nng_tls_config_ca_chain.adoc @@ -0,0 +1,81 @@ +nng_tls_config_ca_chain(3) +========================== +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + 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_chain - configure certificate authority certificate chain + +SYNOPSIS +-------- + +[source, c] +----------- +#include + +int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain, + 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 +'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`. + +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 +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 +------------- + +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. + +SEE ALSO +-------- + +<>, +<>, +<>, +<> + + +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_cert.adoc deleted file mode 100644 index f0ae7351..00000000 --- a/docs/nng_tls_config_cert.adoc +++ /dev/null @@ -1,86 +0,0 @@ -nng_tls_config_cert(3) -====================== -:doctype: manpage -:manmanual: nng -:mansource: nng -:manvolnum: 3 -:icons: font -:source-highlighter: pygments -:copyright: Copyright 2018 Staysail Systems, Inc. \ - Copyright 2018 Capitar IT Group BV \ - 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 - configure own certificate - -SYNOPSIS --------- - -[source, c] ------------ -#include - -int nng_tls_config_cert(nni_tls_config *cfg, const uint8_t *cert, size_t size) ------------ - -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 -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 <> function. - -TIP: This function may be called multiple times, to add additional chains -to a configuration, without affecting those added previously. - -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. - -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 'cert' or 'size' was supplied. - -SEE ALSO --------- - -<>, -<>, -<>, -<> - - -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_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. \ - Copyright 2018 Capitar IT Group BV \ - 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 - -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 -<>, 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 <> 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 --------- - -<>, -<>, -<>, -<>, -<> - - -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 new file mode 100644 index 00000000..485e44ca --- /dev/null +++ b/docs/nng_tls_config_own_cert.adoc @@ -0,0 +1,80 @@ +nng_tls_config_own_cert(3) +========================== +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + 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_own_cert - configure own certificate and key + +SYNOPSIS +-------- + +[source, c] +----------- +#include + +int nng_tls_config_own_cert(nni_tls_config *cfg, const char *cert, + const char *key, const char *pass); +----------- + +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 +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 +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 +strings containing +https://tools.ietf.org/html/rfc7468[PEM] formatted material. + +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 'cert' or 'size' was supplied. + +SEE ALSO +-------- + +<>, +<>, +<> + + +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_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. \ - Copyright 2018 Capitar IT Group BV \ - 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 - -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 -<>. - -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 --------- - -<>, -<>, -<>, -<> - - -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]. -- cgit v1.2.3-70-g09d2