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_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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

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

FURTHER INFORMATION

122       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
123       information.
124

BUGS

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

AUTHORS

131       The libcoap project <libcoap-developers@lists.sourceforge.net>
132
133
134
135coap_tls_library 4.3.1            01/19/2023               COAP_TLS_LIBRARY(3)