man/coap_tls_library.txt.in: New man page covering TLS library support

man/coap_tls_library.txt.in

@@ -0,0 +1,97 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc,tw=0:
+
+coap_tls_library(3)
+===================
+:doctype: manpage
+:man source:   coap_tls_library
+:man version:  @PACKAGE_VERSION@
+:man manual:   libcoap Manual
+
+NAME
+----
+coap_tls_library, coap_dtls_is_supported, coap_tls_is_supported, 
+coap_get_tls_library_version
+- work with CoAP contexts
+
+SYNOPSIS
+--------
+*#include <coap/coap.h>*
+
+*int coap_dtls_is_supported(void);*
+
+*int coap_tls_is_supported(void);*
+
+*coap_tls_version_t *coap_get_tls_library_version(void);*
+
+Link with -lcoap-@LIBCOAP_API_VERSION@.
+
+DESCRIPTION
+-----------
+When the libcoap library was built, it will have been compiled using a 
+specific TLS implementation type (e.g. OpenSSL, GnuTLS, TinyDTLS or noTLS).  
+When the libcoap library is linked into an application, it is possible that 
+the application needs to dynamically determine whether DTLS or TLS is 
+supported, what type of TLS implementation libcoap was compiled with, as well 
+as detect what is the version of the currently loaded TLS library is.
+
+Note: If OpenSSL is being used, then the minimum OpenSSL library version is 
+1.1.0.
+
+Network traffic can be encrypted or un-encrypted with libcoap - how to set 
+this up is described in coap_context(3).
+
+Due to the nature of TLS, there can be Callbacks that are invoked as the TLS 
+session negotiates encryption algorithms, encryption keys etc.
+Where possible, by default, the CoAP layer handles all this automatically.  
+However, there is the flexibility of the Callbacks for imposing additional 
+security checks etc. when PKI is being used.  These callbacks need to need to 
+match the TLS implementation type.
+
+The *coap_dtls_is_supported*() function returns 1 if support for DTLS is 
+enabled, otherwise 0;
+
+The *coap_tls_is_supported*() function returns 1 if support for TLS is 
+enabled, otherwise 0;
+
+The *coap_get_tls_library_version*() function returns the TLS implementation 
+type and library version in a coap_tls_version_t* structure.
+
+[source, c]
+----
+#define COAP_TLS_LIBRARY_NOTLS 0
+#define COAP_TLS_LIBRARY_TINYDTLS 1
+#define COAP_TLS_LIBRARY_OPENSSL 2
+#define COAP_TLS_LIBRARY_GNUTLS 3
+
+typedef struct coap_tls_version_t {
+  uint64_t version; /* Library Version as returned by the TLS library */
+  int type; /* One of COAP_TLS_LIBRARY_* */
+}
+----
+
+RETURN VALUES
+-------------
+*coap_dtls_is_supported*() and *coap_tls_is_supported*() functions
+return 0 on failure, 1 on success.
+
+*coap_get_tls_library_version*() function returns the TLS implementation type 
+and library version in a coap_tls_version_t* structure.
+
+SEE ALSO
+--------
+*coap_context*(3).
+
+FURTHER INFORMATION
+-------------------
+See "RFC7252: The Constrained Application Protocol (CoAP)" for further 
+information.
+
+BUGS
+----
+Please report bugs on the mailing list for libcoap:
+libcoap-developers@lists.sourceforge.net
+
+AUTHORS
+-------
+The libcoap project <libcoap-developers@lists.sourceforge.net>