NAME

       coap_tls_library, coap_dtls_is_supported, coap_tls_is_supported,
       coap_dtls_psk_is_supported, coap_dtls_pki_is_supported, coap_dtls_pkcs11_is_supported,
       coap_dtls_rpk_is_supported, coap_tcp_is_supported, coap_get_tls_library_version,
       coap_string_tls_support, coap_string_tls_version, coap_show_tls_version - Work with CoAP
       TLS libraries

SYNOPSIS

       #include <coap3/coap.h>

       int coap_dtls_is_supported(void);

       int coap_tls_is_supported(void);

       int coap_dtls_psk_is_supported(void);

       int coap_dtls_pki_is_supported(void);

       int coap_dtls_pkcs11_is_supported(void);

       int coap_dtls_rpk_is_supported(void);

       int coap_tcp_is_supported(void);

       coap_tls_version_t *coap_get_tls_library_version(void);

       char *coap_string_tls_support(char *buffer, size_t bufsize);

       char *coap_string_tls_version(char *buffer, size_t bufsize);

       void coap_show_tls_version(coap_log_t level);

       For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls,
       -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to
       get the default (D)TLS library support.

DESCRIPTION

       When the libcoap library was built, it will have been compiled using a specific TLS
       implementation type (e.g. OpenSSL, GnuTLS, Mbed TLS, 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.

       NOTE: If GnuTLS is being used, then the minimum GnuTLS library version is 3.3.0.

       NOTE: If GnuTLS is going to interoperate with TinyDTLS, then a minimum revision of GnuTLS
       3.5.5 which supports CCM algorithms is required by TinyDTLS as TinyDTLS currently only
       supports CCM.

       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.

FUNCTIONS

       Function: coap_dtls_is_supported()

       The coap_dtls_is_supported() function returns 1 if support for DTLS is available,
       otherwise 0;

       Function: coap_tls_is_supported()

       The coap_tls_is_supported() function returns 1 if support for TLS is available, otherwise
       0;

       Function: coap_dtls_psk_is_supported()

       The coap_dtls_psk_is_supported() function returns 1 if support for (D)TLS PSK is
       available, otherwise 0;

       Function: coap_dtls_pki_is_supported()

       The coap_dtls_pki_is_supported() function returns 1 if support for (D)TLS PKI is
       available, otherwise 0;

       Function: coap_dtls_pkcs11_is_supported()

       The coap_dtls_pkcs11_is_supported() function returns 1 if support for (D)TLS PKCS11 is
       available, otherwise 0;

       Function: coap_dtls_rpk_is_supported()

       The coap_dtls_rpk_is_supported() function returns 1 if support for (D)TLS RPK is
       available, otherwise 0;

       Function: coap_tcp_is_supported()

       The coap_tcp_is_supported() function returns 1 if support for TCP is available, otherwise
       0.

       Function: coap_get_tls_library_version()

       The coap_get_tls_library_version() function returns the TLS implementation type and
       library version in a coap_tls_version_t* structure.

           typedef enum coap_tls_library_t {
             COAP_TLS_LIBRARY_NOTLS = 0, /* No DTLS library */
             COAP_TLS_LIBRARY_TINYDTLS,  /* Using TinyDTLS library */
             COAP_TLS_LIBRARY_OPENSSL,   /* Using OpenSSL library */
             COAP_TLS_LIBRARY_GNUTLS,    /* Using GnuTLS library */
             COAP_TLS_LIBRARY_MBEDTLS,   /* Using Mbed TLS library */
           } coap_tls_library_t;

           typedef struct coap_tls_version_t {
             uint64_t version;        /* (D)TLS runtime Library Version */
             coap_tls_library_t type; /* Library type. One of COAP_TLS_LIBRARY_* */
             uint64_t built_version;  /* (D)TLS Built against Library Version */
           }

       Function: coap_string_tls_support()

       The coap_string_tls_support() function is used to update the provided buffer with ascii
       readable information about what type of PSK, PKI etc. keys the current (D)TLS library
       supports. buffer defines the buffer to provide the information and bufsize is the size of
       buffer.

       Function: coap_string_tls_version()

       The coap_string_tls_version() function is used to update the provided buffer with
       information about the current (D)TLS library that libcoap was built against, as well as
       the current linked version of the (D)TLS library. buffer defines the buffer to provide the
       information and bufsize is the size of buffer.

       Function: coap_show_tls_version()

       The coap_show_tls_version() function is used log information about the current (D)TLS
       library that libcoap was built against, as well as the current linked version of the
       (D)TLS library. level defines the minimum logging level for this information to be output
       using coap_log().

RETURN VALUES

       coap_dtls_is_supported(), coap_tls_is_supported(), coap_dtls_psk_is_supported(),
       coap_dtls_pki_is_supported(), coap_dtls_pkcs11_is_supported() and
       coap_dtls_rpk_is_supported() return 0 if there is no support, 1 if support is available.

       coap_get_tls_library_version() returns the TLS implementation type and library version in
       a coap_tls_version_t* structure.

       coap_tcp_is_supported() returns 1 if support for TCP is available, otherwise 0.

       coap_string_tls_version() and coap_string_tls_support() return a pointer to the provided
       buffer.

SEE ALSO

       coap_encryption(3)

FURTHER INFORMATION

       See

       "RFC7252: The Constrained Application Protocol (CoAP)"

       "RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets"

       for further information.

BUGS

       Please report bugs on the mailing list for libcoap:
       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
       https://github.com/obgm/libcoap/issues

AUTHORS

       The libcoap project <libcoap-developers@lists.sourceforge.net>