coap_tls_is_supported(3)

1COAP_TLS_LIBRARY(3)             libcoap Manual             COAP_TLS_LIBRARY(3)
2
3
4

NAME

6       coap_tls_library, coap_dtls_is_supported, coap_tls_is_supported,
7       coap_dtls_psk_is_supported, coap_dtls_pki_is_supported,
8       coap_dtls_pkcs11_is_supported, coap_dtls_rpk_is_supported,
9       coap_tcp_is_supported, coap_get_tls_library_version,
10       coap_string_tls_support, coap_string_tls_version, coap_show_tls_version
11       - Work with CoAP TLS libraries
12

SYNOPSIS

14       #include <coap3/coap.h>
15
16       int coap_dtls_is_supported(void);
17
18       int coap_tls_is_supported(void);
19
20       int coap_dtls_psk_is_supported(void);
21
22       int coap_dtls_pki_is_supported(void);
23
24       int coap_dtls_pkcs11_is_supported(void);
25
26       int coap_dtls_rpk_is_supported(void);
27
28       int coap_tcp_is_supported(void);
29
30       coap_tls_version_t *coap_get_tls_library_version(void);
31
32       char *coap_string_tls_support(char *buffer, size_t bufsize);
33
34       char *coap_string_tls_version(char *buffer, size_t bufsize);
35
36       void coap_show_tls_version(coap_log_t level);
37
38       For specific (D)TLS library support, link with -lcoap-3-notls,
39       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
40       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
41       (D)TLS library support.
42

DESCRIPTION

44       When the libcoap library was built, it will have been compiled using a
45       specific TLS implementation type (e.g. OpenSSL, GnuTLS, Mbed TLS,
46       TinyDTLS or noTLS). When the libcoap library is linked into an
47       application, it is possible that the application needs to dynamically
48       determine whether DTLS or TLS is supported, what type of TLS
49       implementation libcoap was compiled with, as well as detect what is the
50       version of the currently loaded TLS library is.
51
52       NOTE: If OpenSSL is being used, then the minimum OpenSSL library
53       version is 1.1.0.
54
55       NOTE: If GnuTLS is being used, then the minimum GnuTLS library version
56       is 3.3.0.
57
58       NOTE: If GnuTLS is going to interoperate with TinyDTLS, then a minimum
59       revision of GnuTLS 3.5.5 which supports CCM algorithms is required by
60       TinyDTLS as TinyDTLS currently only supports CCM.
61
62       Network traffic can be encrypted or un-encrypted with libcoap - how to
63       set this up is described in coap_context(3).
64
65       Due to the nature of TLS, there can be Callbacks that are invoked as
66       the TLS session negotiates encryption algorithms, encryption keys etc.
67       Where possible, by default, the CoAP layer handles all this
68       automatically. However, there is the flexibility of the Callbacks for
69       imposing additional security checks etc. when PKI is being used. These
70       callbacks need to need to match the TLS implementation type.
71

FUNCTIONS

73       Function: coap_dtls_is_supported()
74
75       The coap_dtls_is_supported() function returns 1 if support for DTLS is
76       available, otherwise 0;
77
78       Function: coap_tls_is_supported()
79
80       The coap_tls_is_supported() function returns 1 if support for TLS is
81       available, otherwise 0;
82
83       Function: coap_dtls_psk_is_supported()
84
85       The coap_dtls_psk_is_supported() function returns 1 if support for
86       (D)TLS PSK is available, otherwise 0;
87
88       Function: coap_dtls_pki_is_supported()
89
90       The coap_dtls_pki_is_supported() function returns 1 if support for
91       (D)TLS PKI is available, otherwise 0;
92
93       Function: coap_dtls_pkcs11_is_supported()
94
95       The coap_dtls_pkcs11_is_supported() function returns 1 if support for
96       (D)TLS PKCS11 is available, otherwise 0;
97
98       Function: coap_dtls_rpk_is_supported()
99
100       The coap_dtls_rpk_is_supported() function returns 1 if support for
101       (D)TLS RPK is available, otherwise 0;
102
103       Function: coap_tcp_is_supported()
104
105       The coap_tcp_is_supported() function returns 1 if support for TCP is
106       available, otherwise 0.
107
108       Function: coap_get_tls_library_version()
109
110       The coap_get_tls_library_version() function returns the TLS
111       implementation type and library version in a coap_tls_version_t*
112       structure.
113
114           typedef enum coap_tls_library_t {
115             COAP_TLS_LIBRARY_NOTLS = 0, /* No DTLS library */
116             COAP_TLS_LIBRARY_TINYDTLS,  /* Using TinyDTLS library */
117             COAP_TLS_LIBRARY_OPENSSL,   /* Using OpenSSL library */
118             COAP_TLS_LIBRARY_GNUTLS,    /* Using GnuTLS library */
119             COAP_TLS_LIBRARY_MBEDTLS,   /* Using Mbed TLS library */
120           } coap_tls_library_t;
121
122           typedef struct coap_tls_version_t {
123             uint64_t version;        /* (D)TLS runtime Library Version */
124             coap_tls_library_t type; /* Library type. One of COAP_TLS_LIBRARY_* */
125             uint64_t built_version;  /* (D)TLS Built against Library Version */
126           }
127
128       Function: coap_string_tls_support()
129
130       The coap_string_tls_support() function is used to update the provided
131       buffer with ascii readable information about what type of PSK, PKI etc.
132       keys the current (D)TLS library supports. buffer defines the buffer to
133       provide the information and bufsize is the size of buffer.
134
135       Function: coap_string_tls_version()
136
137       The coap_string_tls_version() function is used to update the provided
138       buffer with information about the current (D)TLS library that libcoap
139       was built against, as well as the current linked version of the (D)TLS
140       library. buffer defines the buffer to provide the information and
141       bufsize is the size of buffer.
142
143       Function: coap_show_tls_version()
144
145       The coap_show_tls_version() function is used log information about the
146       current (D)TLS library that libcoap was built against, as well as the
147       current linked version of the (D)TLS library. level defines the minimum
148       logging level for this information to be output using coap_log().
149

RETURN VALUES

151       coap_dtls_is_supported(), coap_tls_is_supported(),
152       coap_dtls_psk_is_supported(), coap_dtls_pki_is_supported(),
153       coap_dtls_pkcs11_is_supported() and coap_dtls_rpk_is_supported() return
154       0 if there is no support, 1 if support is available.
155
156       coap_get_tls_library_version() returns the TLS implementation type and
157       library version in a coap_tls_version_t* structure.
158
159       coap_tcp_is_supported() returns 1 if support for TCP is available,
160       otherwise 0.
161
162       coap_string_tls_version() and coap_string_tls_support() return a
163       pointer to the provided buffer.
164

FURTHER INFORMATION

169       See
170
171       "RFC7252: The Constrained Application Protocol (CoAP)"
172
173       "RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and
174       WebSockets"
175
176       for further information.
177

BUGS

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

AUTHORS

184       The libcoap project <libcoap-developers@lists.sourceforge.net>
185
186
187
188coap_tls_library 4.3.4            10/09/2023               COAP_TLS_LIBRARY(3)