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