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_dtls_psk_is_supported, 17coap_dtls_pki_is_supported, 18coap_dtls_pkcs11_is_supported, 19coap_dtls_rpk_is_supported, 20coap_tcp_is_supported, 21coap_get_tls_library_version, 22coap_string_tls_support, 23coap_string_tls_version, 24coap_show_tls_version 25- Work with CoAP TLS libraries 26 27SYNOPSIS 28-------- 29*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 30 31*int coap_dtls_is_supported(void);* 32 33*int coap_tls_is_supported(void);* 34 35*int coap_dtls_psk_is_supported(void);* 36 37*int coap_dtls_pki_is_supported(void);* 38 39*int coap_dtls_pkcs11_is_supported(void);* 40 41*int coap_dtls_rpk_is_supported(void);* 42 43*int coap_tcp_is_supported(void);* 44 45*coap_tls_version_t *coap_get_tls_library_version(void);* 46 47*char *coap_string_tls_support(char *_buffer_, size_t _bufsize_);* 48 49*char *coap_string_tls_version(char *_buffer_, size_t _bufsize_);* 50 51*void coap_show_tls_version(coap_log_t _level_);* 52 53For specific (D)TLS library support, link with 54*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 55*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 56or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 57*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 58 59DESCRIPTION 60----------- 61When the libcoap library was built, it will have been compiled using a 62specific TLS implementation type (e.g. https://www.openssl.org[OpenSSL], 63https://www.gnutls.org[GnuTLS], 64https://www.trustedfirmware.org/projects/mbed-tls/[Mbed TLS], 65https://github.com/eclipse/tinydtls[TinyDTLS] or noTLS). 66When the libcoap library is linked into an application, it is possible that 67the application needs to dynamically determine whether DTLS or TLS is 68supported, what type of TLS implementation libcoap was compiled with, as well 69as detect what is the version of the currently loaded TLS library is. 70 71*NOTE:* If OpenSSL is being used, then the minimum OpenSSL library version is 721.1.0. 73 74*NOTE:* If GnuTLS is being used, then the minimum GnuTLS library version is 753.3.0. 76 77*NOTE:* If GnuTLS is going to interoperate with TinyDTLS, then a minimum 78revision of GnuTLS 3.5.5 which supports CCM algorithms is required 79by TinyDTLS as TinyDTLS currently only supports CCM. 80 81Network traffic can be encrypted or un-encrypted with libcoap - how to set 82this up is described in *coap_context*(3). 83 84Due to the nature of TLS, there can be Callbacks that are invoked as the TLS 85session negotiates encryption algorithms, encryption keys etc. 86Where possible, by default, the CoAP layer handles all this automatically. 87However, there is the flexibility of the Callbacks for imposing additional 88security checks etc. when PKI is being used. These callbacks need to need to 89match the TLS implementation type. 90 91FUNCTIONS 92--------- 93 94*Function: coap_dtls_is_supported()* 95 96The *coap_dtls_is_supported*() function returns 1 if support for DTLS is 97available, otherwise 0; 98 99*Function: coap_tls_is_supported()* 100 101The *coap_tls_is_supported*() function returns 1 if support for TLS is 102available, otherwise 0; 103 104*Function: coap_dtls_psk_is_supported()* 105 106The *coap_dtls_psk_is_supported*() function returns 1 if support for (D)TLS PSK 107is available, otherwise 0; 108 109*Function: coap_dtls_pki_is_supported()* 110 111The *coap_dtls_pki_is_supported*() function returns 1 if support for (D)TLS PKI 112is available, otherwise 0; 113 114*Function: coap_dtls_pkcs11_is_supported()* 115 116The *coap_dtls_pkcs11_is_supported*() function returns 1 if support for (D)TLS 117PKCS11 is available, otherwise 0; 118 119*Function: coap_dtls_rpk_is_supported()* 120 121The *coap_dtls_rpk_is_supported*() function returns 1 if support for (D)TLS RPK 122is available, otherwise 0; 123 124*Function: coap_tcp_is_supported()* 125 126The *coap_tcp_is_supported*() function returns 1 if support for TCP is 127available, otherwise 0. 128 129*Function: coap_get_tls_library_version()* 130 131The *coap_get_tls_library_version*() function returns the TLS implementation 132type and library version in a coap_tls_version_t* structure. 133 134[source, c] 135---- 136typedef enum coap_tls_library_t { 137 COAP_TLS_LIBRARY_NOTLS = 0, /* No DTLS library */ 138 COAP_TLS_LIBRARY_TINYDTLS, /* Using TinyDTLS library */ 139 COAP_TLS_LIBRARY_OPENSSL, /* Using OpenSSL library */ 140 COAP_TLS_LIBRARY_GNUTLS, /* Using GnuTLS library */ 141 COAP_TLS_LIBRARY_MBEDTLS, /* Using Mbed TLS library */ 142} coap_tls_library_t; 143 144typedef struct coap_tls_version_t { 145 uint64_t version; /* (D)TLS runtime Library Version */ 146 coap_tls_library_t type; /* Library type. One of COAP_TLS_LIBRARY_* */ 147 uint64_t built_version; /* (D)TLS Built against Library Version */ 148} 149---- 150 151*Function: coap_string_tls_support()* 152 153The *coap_string_tls_support*() function is used to update the provided buffer 154with ascii readable information about what type of PSK, PKI etc. keys the 155current (D)TLS library supports. 156_buffer_ defines the buffer to provide the information and _bufsize_ is the 157size of _buffer_. 158 159*Function: coap_string_tls_version()* 160 161The *coap_string_tls_version*() function is used to update the provided buffer 162with information about the current (D)TLS library that libcoap was built 163against, as well as the current linked version of the (D)TLS library. 164_buffer_ defines the buffer to provide the information and _bufsize_ is the 165size of _buffer_. 166 167*Function: coap_show_tls_version()* 168 169The *coap_show_tls_version*() function is used log information about the 170current (D)TLS library that libcoap was built against, as well as the current 171linked version of the (D)TLS library. _level_ defines the minimum logging level 172for this information to be output using coap_log(). 173 174RETURN VALUES 175------------- 176*coap_dtls_is_supported*(), *coap_tls_is_supported*(), 177*coap_dtls_psk_is_supported*(), *coap_dtls_pki_is_supported*(), 178*coap_dtls_pkcs11_is_supported*() and *coap_dtls_rpk_is_supported*() 179return 0 if there is no support, 1 if support is available. 180 181*coap_get_tls_library_version*() returns the TLS implementation type 182and library version in a coap_tls_version_t* structure. 183 184*coap_tcp_is_supported*() returns 1 if support for TCP is 185available, otherwise 0. 186 187*coap_string_tls_version*() and *coap_string_tls_support*() return 188a pointer to the provided buffer. 189 190SEE ALSO 191-------- 192*coap_encryption*(3) 193 194FURTHER INFORMATION 195------------------- 196See 197 198"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]" 199 200"https://rfc-editor.org/rfc/rfc8323[RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets]" 201 202for further information. 203 204BUGS 205---- 206Please report bugs on the mailing list for libcoap: 207libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 208https://github.com/obgm/libcoap/issues 209 210AUTHORS 211------- 212The libcoap project <libcoap-developers@lists.sourceforge.net> 213