diff --git a/man/coap_tls_library.txt.in b/man/coap_tls_library.txt.in new file mode 100644 index 00000000..b0310d21 --- /dev/null +++ b/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 * + +*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