1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_tls_library(3) 5=================== 6:doctype: manpage 7:man source: coap_tls_library 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_tls_library, 14coap_dtls_is_supported, 15coap_tls_is_supported, 16coap_tcp_is_supported, 17coap_get_tls_library_version, 18coap_string_tls_support, 19coap_string_tls_version, 20coap_show_tls_version 21- Work with CoAP TLS libraries 22 23SYNOPSIS 24-------- 25*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 26 27*int coap_dtls_is_supported(void);* 28 29*int coap_tls_is_supported(void);* 30 31*int coap_tcp_is_supported(void);* 32 33*coap_tls_version_t *coap_get_tls_library_version(void);* 34 35*char *coap_string_tls_support(char *_buffer_, size_t _bufsize_);* 36 37*char *coap_string_tls_version(char *_buffer_, size_t _bufsize_);* 38 39*void coap_show_tls_version(coap_log_t _level_);* 40 41For specific (D)TLS library support, link with 42*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 43*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 44or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 45*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 46 47DESCRIPTION 48----------- 49When the libcoap library was built, it will have been compiled using a 50specific TLS implementation type (e.g. OpenSSL, GnuTLS, Mbed TLS, TinyDTLS or 51noTLS). 52When the libcoap library is linked into an application, it is possible that 53the application needs to dynamically determine whether DTLS or TLS is 54supported, what type of TLS implementation libcoap was compiled with, as well 55as detect what is the version of the currently loaded TLS library is. 56 57*NOTE:* If OpenSSL is being used, then the minimum OpenSSL library version is 581.1.0. 59 60*NOTE:* If GnuTLS is being used, then the minimum GnuTLS library version is 613.3.0. 62 63*NOTE:* If GnuTLS is going to interoperate with TinyDTLS, then a minimum 64revision of GnuTLS 3.5.5 which supports CCM algorithms is required 65by TinyDTLS as TinyDTLS currently only supports CCM. 66 67Network traffic can be encrypted or un-encrypted with libcoap - how to set 68this up is described in *coap_context*(3). 69 70Due to the nature of TLS, there can be Callbacks that are invoked as the TLS 71session negotiates encryption algorithms, encryption keys etc. 72Where possible, by default, the CoAP layer handles all this automatically. 73However, there is the flexibility of the Callbacks for imposing additional 74security checks etc. when PKI is being used. These callbacks need to need to 75match the TLS implementation type. 76 77The *coap_dtls_is_supported*() function returns 1 if support for DTLS is 78enabled, otherwise 0; 79 80The *coap_tls_is_supported*() function returns 1 if support for TLS is 81enabled, otherwise 0; 82 83The *coap_tcp_is_supported*() function returns 1 if support for TCP is 84enabled, otherwise 0. 85 86The *coap_get_tls_library_version*() function returns the TLS implementation 87type and library version in a coap_tls_version_t* structure. 88 89The *coap_string_tls_support*() function is used to update the provided buffer 90with ascii readable information about what type of PSK, PKI etc. keys the 91current (D)TLS library supports. 92_buffer_ defines the buffer to provide the information and _bufsize_ is the 93size of _buffer_. 94 95The *coap_string_tls_version*() function is used to update the provided buffer 96with information about the current (D)TLS library that libcoap was built 97against, as well as the current linked version of the (D)TLS library. 98_buffer_ defines the buffer to provide the information and _bufsize_ is the 99size of _buffer_. 100 101The *coap_show_tls_version*() function is used log information about the 102current (D)TLS library that libcoap was built against, as well as the current 103linked version of the (D)TLS library. _level_ defines the minimum logging level 104for this information to be output using coap_log(). 105 106[source, c] 107---- 108typedef enum coap_tls_library_t { 109 COAP_TLS_LIBRARY_NOTLS = 0, /* No DTLS library */ 110 COAP_TLS_LIBRARY_TINYDTLS, /* Using TinyDTLS library */ 111 COAP_TLS_LIBRARY_OPENSSL, /* Using OpenSSL library */ 112 COAP_TLS_LIBRARY_GNUTLS, /* Using GnuTLS library */ 113 COAP_TLS_LIBRARY_MBEDTLS, /* Using Mbed TLS library */ 114} coap_tls_library_t; 115 116typedef struct coap_tls_version_t { 117 uint64_t version; /* (D)TLS runtime Library Version */ 118 coap_tls_library_t type; /* Library type. One of COAP_TLS_LIBRARY_* */ 119 uint64_t built_version; /* (D)TLS Built against Library Version */ 120} 121---- 122 123RETURN VALUES 124------------- 125*coap_dtls_is_supported*() and *coap_tls_is_supported*() functions 126return 0 if there is no support, 1 if support is available. 127 128*coap_get_tls_library_version*() function returns the TLS implementation type 129and library version in a coap_tls_version_t* structure. 130 131The *coap_tcp_is_supported*() function returns 1 if support for TCP is 132enabled, otherwise 0. 133 134*coap_string_tls_version*() function returns a pointer to the provided buffer. 135 136SEE ALSO 137-------- 138*coap_encryption*(3). 139 140FURTHER INFORMATION 141------------------- 142See "RFC7252: The Constrained Application Protocol (CoAP)" for further 143information. 144 145BUGS 146---- 147Please report bugs on the mailing list for libcoap: 148libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 149https://github.com/obgm/libcoap/issues 150 151AUTHORS 152------- 153The libcoap project <libcoap-developers@lists.sourceforge.net> 154