'\" t
.\" Title: coap_tls_library
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 05/14/2022
.\" Manual: libcoap Manual
.\" Source: coap_tls_library 4.2.1
.\" Language: English
.\"
.TH "COAP_TLS_LIBRARY" "3" "05/14/2022" "coap_tls_library 4\&.2\&.1" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_tls_library, coap_dtls_is_supported, coap_tls_is_supported, coap_get_tls_library_version, coap_string_tls_version, coap_show_tls_version \- Work with CoAP contexts
.SH "SYNOPSIS"
.sp
\fB#include \fR
.sp
\fBint coap_dtls_is_supported(void);\fR
.sp
\fBint coap_tls_is_supported(void);\fR
.sp
\fBcoap_tls_version_t *coap_get_tls_library_version(void);\fR
.sp
*char *coap_string_tls_version(char *\fIbuffer\fR, size_t \fIbufsize\fR);
.sp
\fBvoid coap_show_tls_version(coap_log_t \fR\fB\fIlevel\fR\fR\fB);\fR
.sp
Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&.
.SH "DESCRIPTION"
.sp
When the libcoap library was built, it will have been compiled using a specific TLS implementation type (e\&.g\&. OpenSSL, GnuTLS, TinyDTLS or noTLS)\&. When the libcoap library is linked into an application, it is possible that the application needs to dynamically determine whether DTLS or TLS is supported, what type of TLS implementation libcoap was compiled with, as well as detect what is the version of the currently loaded TLS library is\&.
.sp
\fBNOTE:\fR If OpenSSL is being used, then the minimum OpenSSL library version is 1\&.1\&.0\&.
.sp
\fBNOTE:\fR If GnuTLS is being used, then the minimum GnuTLS library version is 3\&.3\&.0\&.
.sp
\fBNOTE:\fR If GnuTLS is going to interoperate with TinyDTLS, then a minimum revision of GnuTLS 3\&.5\&.5 which supports CCM algorithms is required by TinyDTLS as TinyDTLS currently only supports CCM\&.
.sp
Network traffic can be encrypted or un\-encrypted with libcoap \- how to set this up is described in \fBcoap_context\fR(3)\&.
.sp
Due to the nature of TLS, there can be Callbacks that are invoked as the TLS session negotiates encryption algorithms, encryption keys etc\&. Where possible, by default, the CoAP layer handles all this automatically\&. However, there is the flexibility of the Callbacks for imposing additional security checks etc\&. when PKI is being used\&. These callbacks need to need to match the TLS implementation type\&.
.sp
The \fBcoap_dtls_is_supported\fR() function returns 1 if support for DTLS is enabled, otherwise 0;
.sp
The \fBcoap_tls_is_supported\fR() function returns 1 if support for TLS is enabled, otherwise 0;
.sp
The \fBcoap_get_tls_library_version\fR() function returns the TLS implementation type and library version in a coap_tls_version_t* structure\&.
.sp
The \fBcoap_string_tls_version\fR() function is used to update the provided buffer with information about the current (D)TLS library that libcoap was built against, as well as the current linked version of the (D)TLS library\&. \fIbuffer\fR defines the buffer to provide the information and \fIbufsize\fR is the size of \fIbuffer\fR\&.
.sp
The \fBcoap_show_tls_version\fR() function is used log information about the current (D)TLS library that libcoap was built against, as well as the current linked version of the (D)TLS library\&. \fIlevel\fR defines the minimum logging level for this information to be output using coap_log()\&.
.sp
.if n \{\
.RS 4
.\}
.nf
typedef enum coap_tls_library_t {
COAP_TLS_LIBRARY_NOTLS = 0, /**< No DTLS library */
COAP_TLS_LIBRARY_TINYDTLS, /**< Using TinyDTLS library */
COAP_TLS_LIBRARY_OPENSSL, /**< Using OpenSSL library */
COAP_TLS_LIBRARY_GNUTLS, /**< Using GnuTLS library */
} coap_tls_library_t;
typedef struct coap_tls_version_t {
uint64_t version; /* (D)TLS runtime Library Version */
coap_tls_library_t type; /**< Library type\&. One of COAP_TLS_LIBRARY_* */
uint64_t built_version; /* (D)TLS Built against Library Version */
}
.fi
.if n \{\
.RE
.\}
.SH "RETURN VALUES"
.sp
\fBcoap_dtls_is_supported\fR() and \fBcoap_tls_is_supported\fR() functions return 0 if there is no support, 1 if support is available\&.
.sp
\fBcoap_get_tls_library_version\fR() function returns the TLS implementation type and library version in a coap_tls_version_t* structure\&.
.sp
\fBcoap_string_tls_version\fR() function returns a pointer to the provided buffer\&.
.SH "SEE ALSO"
.sp
\fBcoap_context\fR(3) and \fBcoap_logging\fR(3)\&.
.SH "FURTHER INFORMATION"
.sp
See "RFC7252: The Constrained Application Protocol (CoAP)" for further information\&.
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project