COAP_TLS_LIBRARY(3)

💖 COAP_TLS_LIBRARY(3) — the libcoap manual, but make it make sense 💖

okay bestie so this is a page from the libcoap Manual and it's literally all about the TLS side of things — coap_tls_library, coap_get_tls_library_version, coap_string_tls_support, coap_string_tls_version, coap_show_tls_version, coap_tls_engine_configure and coap_tls_engine_remove. The whole vibe: work with CoAP TLS libraries. 🎀

---

✨ NAME ✨

coap_tls_library, coap_get_tls_library_version, coap_string_tls_support, coap_string_tls_version, coap_show_tls_version, coap_tls_engine_configure, coap_tls_engine_remove — all of these are about working with CoAP TLS libraries. that's the whole job. 💅

---

🦋 SYNOPSIS 🦋

#include <coap3/coap.h>

coap_tls_version_t *coap_get_tls_library_version(void);

char *coap_string_tls_support(char *buffer, size_t bufsize);

char *coap_string_tls_version(char *buffer, size_t bufsize);

void coap_show_tls_version(coap_log_t level);

int coap_tls_engine_configure(coap_str_const_t *conf_mem);

int coap_tls_engine_remove(void);

so like, for specific (D)TLS library support you link with one of these bad boys: -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls, -lcoap-3-wolfssl or -lcoap-3-tinydtls. otherwise you just link with -lcoap-3 and get whatever the default (D)TLS library support is. slay. 🔥

---

🌸 DESCRIPTION 🌸

so when the libcoap library got built, it was compiled against one specific TLS implementation type (think OpenSSL, GnuTLS, Mbed TLS, wolfSSL, TinyDTLS, or noTLS at all). and here's the thing — when libcoap gets linked into an app, that app might need to dynamically figure out:

• whether DTLS or TLS is even supported,
• what type of TLS implementation libcoap was compiled with,
• and what the version of the currently loaded TLS library actually is.

that's the whole point of these functions, no cap. 🧚

NOTE: if OpenSSL is being used, then the minimum OpenSSL library version is 1.1.0. don't come at me with anything older, bestie.

NOTE: if GnuTLS is being used, then the minimum GnuTLS library version is 3.3.0. periodt.

NOTE: 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 — because TinyDTLS currently only supports CCM. that's just how it is. 💀

network traffic can be encrypted or un-encrypted with libcoap — how to set that up is described in coap_context(3). go read it, i'll wait. 🫶

and because TLS is, well, TLS — there can be Callbacks that get invoked as the TLS session negotiates encryption algorithms, encryption keys, etc. where possible, by default, the CoAP layer handles all this automatically. but there's flexibility in those Callbacks for imposing additional security checks etc. when PKI is being used. these callbacks need to need to match the TLS implementation type. (yes, the original says "need to need to" — iconic, honestly, i'm keeping it.) 😭

---

👑 FUNCTIONS 👑

⭐ Function: coap_get_tls_library_version()

the coap_get_tls_library_version() function returns the TLS implementation type and library version in a coap_tls_version_t* structure. look at it:

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_MBEDTLS,   /* Using Mbed TLS library */
  COAP_TLS_LIBRARY_WOLFSSL,   /* Using wolfSSL 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 */
}

⭐ Function: coap_string_tls_support()

the coap_string_tls_support() function is used to update the provided buffer with ascii readable information about what type of PSK, PKI etc. keys the current (D)TLS library supports. buffer defines the buffer to provide the information and bufsize is the size of buffer. simple as. ✨

⭐ Function: coap_string_tls_version()

the coap_string_tls_version() 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. buffer defines the buffer to provide the information and bufsize is the size of buffer. yes, both versions. it's giving thorough. 💅

⭐ Function: coap_show_tls_version()

the coap_show_tls_version() 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. level defines the minimum logging level for this information to be output using coap_log(). 🎀

⭐ Function: coap_tls_engine_configure()

the coap_tls_engine_configure() function is used to configure a TLS ENGINE (currently only OpenSSL). it parses the provided configuration in conf_mem and initializes the ENGINE appropriately. the format of the parameters is documented in coap-tls-engine-conf(5). go check that page, iykyk. 🔍

⭐ Function: coap_tls_engine_remove()

the coap_tls_engine_remove() function removes a previously configured TLS ENGINE. this function is called when coap_free_context() is called. so it's lowkey automatic, but now you know. 🦋

---

🌈 RETURN VALUES 🌈

• coap_get_tls_library_version() returns the TLS implementation type and library version in a coap_tls_version_t* structure.
• coap_string_tls_version() and coap_string_tls_support() return a pointer to the provided buffer.
• coap_tls_engine_configure() returns 1 if the TLS ENGINE was successfully configured, otherwise 0.
• coap_tls_engine_remove() returns 1 if the TLS ENGINE was successfully removed, otherwise 0.

like, 1 = good vibes, 0 = not it. 💯

---

🍓 EXAMPLES 🍓

*CoAP Server DTLS PKI Setup with OpenSSL Engine *

here's a whole main-character example, bestie. every line, verbatim, don't touch:

#include <coap3/coap.h>

#define ENGINE_CONFIG \
  "engine:pkcs11\n" \
  "enable-methods:0xffff\n" \
  "post-cmd:PIN:1234\n"

/*
 * Set up PKI encryption information
 */
static coap_context_t *
setup_server_context_pki(const char *public_cert_file,
                         const char *private_key,
                         const char *ca_file) {
  coap_endpoint_t *endpoint;
  coap_address_t listen_addr;
  coap_dtls_pki_t dtls_pki;
  coap_context_t *context;
  coap_str_const_t *engine_conf = coap_make_str_const(ENGINE_CONFIG);

  /* See coap_supported(3) */
  if (!coap_dtls_is_supported())
    return NULL;

  context = coap_new_context(NULL);
  if (!context)
    return NULL;
  /* See coap_block(3) */
  coap_context_set_block_mode(context,
                              COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);

  /* To get full logging of any issues here, you need to
   *
   * coap_set_log_level(COAP_LOG_DEBUG);
   * coap_set_dtls_log_level(COAP_LOG_DEBUG);
   */
  if (!coap_tls_engine_configure(engine_conf))
    return NULL;

  memset(&dtls_pki, 0, sizeof(dtls_pki));

  /* see coap_encryption(3) */
  dtls_pki.version                 = COAP_DTLS_PKI_SETUP_VERSION;
  dtls_pki.verify_peer_cert        = 1;
  dtls_pki.check_common_ca         = 1;
  dtls_pki.allow_self_signed       = 1;
  dtls_pki.allow_expired_certs     = 1;
  dtls_pki.cert_chain_validation   = 1;
  dtls_pki.cert_chain_verify_depth = 1;
  dtls_pki.check_cert_revocation   = 1;
  dtls_pki.allow_no_crl            = 1;
  dtls_pki.allow_expired_crl       = 1;
  dtls_pki.pki_key.key_type                      = COAP_PKI_KEY_DEFINE;
  dtls_pki.pki_key.key.define.ca.s_byte          = ca_file;
  dtls_pki.pki_key.key.define.public_cert.s_byte = public_cert_file;
  dtls_pki.pki_key.key.define.private_key.s_byte = private_key;
  dtls_pki.pki_key.key.define.public_cert_def    = COAP_PKI_KEY_DEF_PEM;
  dtls_pki.pki_key.key.define.private_key_def    = COAP_PKI_KEY_DEF_ENGINE;
  dtls_pki.pki_key.key.define.ca_def             = COAP_PKI_KEY_DEF_PEM;

  if (coap_context_set_pki(context, &dtls_pki)) {
    coap_free_context(context);
    return NULL;
  }

  /* See coap_address(3) */
  coap_address_init(&listen_addr);
  listen_addr.addr.sa.sa_family = AF_INET;
  listen_addr.addr.sin.sin_port = htons(5684);

  endpoint = coap_new_endpoint(context, &listen_addr, COAP_PROTO_DTLS);
  if (!endpoint) {
    coap_free_context(context);
    return NULL;
  }

  /* Initialize resources - See coap_resource(3) init_resources() example */

  return context;
}

---

🔥 SEE ALSO 🔥

coap_encryption(3) and coap_supported(3) — go read those next, bestie, they're the vibe-adjacent pages. 🫶

---

💜 FURTHER INFORMATION 💜

see:

"RFC7252: The Constrained Application Protocol (CoAP)"

"RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets"

for further information. yes, actual RFCs. read them at your own pace, i believe in you. 📚

---

🙈 BUGS 🙈

please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs.

please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. we love a contributor. 💖

---

🧚 AUTHORS 🧚

the libcoap project <libcoap-developers@lists.sourceforge.net>

---

and that's the whole page, bestie!! ✨ this was coap_tls_library version 4.3.5b, dated 04/28/2026, and that's the cute little sign-off from your favorite manual. mwah. 💅🎀💖