COAP_ENDPOINT_CLIENT(3)

💖 COAP_ENDPOINT_CLIENT(3) 💖

from the libcoap Manual — okay bestie, this is the client-side CoAP setup page, and we’re gonna make it make sense 💅

🎀 NAME 🎀

This page is all about working with CoAP client endpoints, and the whole squad is:

• coap_endpoint_client
• coap_new_client_session
• coap_new_client_session_psk2
• coap_new_client_session_pki
• coap_session_set_mtu
• coap_session_max_pdu_size
• coap_mcast_set_hops

✨ SYNOPSIS ✨

Start with this include, no cap:

#include <coap3/coap.h>

Then the function signatures, exactly as they are:

coap_session_t *coap_new_client_session(coap_context_t *context, const
coap_address_t *local_if, const coap_address_t *server, coap_proto_t
proto);

coap_session_t *coap_new_client_session_psk2(coap_context_t *context,
const coap_address_t *local_if, const coap_address_t *server,
coap_proto_t proto, coap_dtls_cpsk_t *setup_data);

coap_session_t *coap_new_client_session_pki(coap_context_t *context,
const coap_address_t *local_if, const coap_address_t *server,
coap_proto_t proto, coap_dtls_pki_t *setup_data);

void coap_session_set_mtu(coap_session_t *session, unsigned mtu);

size_t coap_session_max_pdu_size(const coap_session_t *session);

int coap_mcast_set_hops(coap_session_t *session, size_t hops);

For specific (D)TLS library support, link with one of these, bestie:

• -lcoap-3-notls
• -lcoap-3-gnutls
• -lcoap-3-openssl
• -lcoap-3-mbedtls
• -lcoap-3-wolfssl
• -lcoap-3-tinydtls

Otherwise, link with -lcoap-3 to get the default (D)TLS library support. ✨

🌸 DESCRIPTION 🌸

Okay so this man page is focused on setting up a CoAP client endpoint, which means creating the CoAP session you use to connect to a server. For the server-side counterpart, see coap_endpoint_server(3).

There is no need to call coap_new_endpoint(3) for a client as well as one of the coap_new_client_server*() functions. That’s the rule, periodt.

The CoAP stack’s global state is stored in a coap_context_t context object. Resources, Endpoints and Sessions are associated with this context object. There can be more than one coap_context_t object per application, and it is up to the application to manage each one accordingly. 💅

A CoAP session maintains the state of an ongoing connection between a Client and Server, and that state is stored in a coap_session_t session object. A CoAP session is tracked by local port, CoAP protocol, remote IP address and remote port — or, in the case of Unix Domain sockets, the local path and the remote path. 🦋

The session network traffic can be encrypted or un-encrypted if there is an underlying TLS library.

If (D)TLS is going to be used for encrypting the network traffic, then the (D)TLS information for Pre-Shared Keys (PSK) or Public Key Infrastructure (PKI) needs to be configured before any network traffic starts to flow. For Clients, this is done during the Client session set up. 🔥

For Clients, all the encryption information can be held at the (D)TLS context and CoAP context levels, or at the (D)TLS session and CoAP session levels. If defined at the context level, then when a session is created, it will inherit the context definitions — unless they have separately been defined for the session level, in which case the session version will get used. Typically the information will be configured at the session level for Clients. 👑

In principle the set-up sequence for CoAP client endpoints looks like this:

coap_new_context()
coap_context_set_pki_root_cas() - if the root CAs need to be updated and using PKI
coap_new_client_session(), coap_new_client_session_pki() or coap_new_client_session_psk2()

Multiple client endpoints and hence sessions are supported per context. Slay.

Different CoAP protocols can be defined for proto — the current supported list is:

COAP_PROTO_UDP
COAP_PROTO_DTLS
COAP_PROTO_TCP
COAP_PROTO_TLS
COAP_PROTO_WS
COAP_PROTO_WSS

coap_tcp_is_supported(3), coap_dtls_is_supported(3), coap_tls_is_supported(3), coap_ws_is_supported(3) and coap_wss_is_supported(3) can be used for checking whether the underlying TCP, (D)TLS or WebSocket protocol support is available. See coap_tls_library(3) for further information on the types of (D)TLS sessions supported. 🧚

Libcoap supports 3 different socket types:

• AF_INET — IPv4 IP addresses and ports
• AF_INET6 — IPv6 IP addresses and ports and can be dual IPv4/IPv6 stacked
• AF_UNIX — Unix Domain using file path names

For AF_INET and AF_INET6, the client does not need to specify a local IP address and/or port as default values will get filled in. However for AF_UNIX, the local pathname must be provided and must be unique per client session. This unique local pathname will get deleted on the session being properly closed at application exit. 🫶

The client must specify IP and port when defining the coap_address_t (see coap_address_t(3)) for the remote end of the session if AF_INET or AF_INET6. If port is 0, then the default CoAP port is used instead. If AF_UNIX, the unix domain path to connect to must be specified. 💖

💅 FUNCTIONS 💅

Function: coap_new_client_session()

The coap_new_client_session() function creates a client endpoint for a specific context and initiates a new client session to the specified server using the CoAP protocol proto as defined above. If the port is set to 0 in server (for AF_INET or AF_INET6), then the default CoAP port is used. ✨

Normally local_if would be set to NULL, but by specifying local_if the source of the network session can be bound to a specific IP address or port. For AF_UNIX, local_if must be specified pointing to an appropriate coap_address_t. If local_if is defined, the address families for local_if and server must be identical. The session will initially have a reference count of 1. 👑

To stop using a client session, the reference count must be decremented to 0 by calling coap_session_release(3). See coap_session(3). This will remove the client endpoint’s session and all its associated information. 🎀

Function: coap_new_client_session_pki()

The coap_new_client_session_pki() function, for a specific context, is used to configure the (D)TLS context using the setup_data variables as defined in the coap_dtls_pki_t structure in the newly created endpoint session — see coap_encryption(3). The connection is to the specified server using the CoAP protocol proto as defined above. If the port is set to 0 in server (for AF_INET or AF_INET6), then the default CoAP port is used. 🔥

Normally local_if would be set to NULL, but by specifying local_if the source of the network session can be bound to a specific IP address or port. For AF_UNIX, local_if must be specified pointing to an appropriate coap_address_t. If local_if is defined, the address families for local_if and server must be identical. The session will initially have a reference count of 1. 💜

To stop using a client session, the reference count must be decremented to 0 by calling coap_session_release(3). See coap_session(3). This will remove the client endpoint’s session and all its associated information. 🌸

Function: coap_new_client_session_psk2()

The coap_new_client_session_psk2() function, for a specific context, is used to configure the (D)TLS context using the setup_data variables as defined in the coap_dtls_cpsk_t structure in the newly created endpoint session — see coap_encryption(3). The connection is to the specified server using the CoAP protocol proto as defined above. If the port is set to 0 in server (for AF_INET or AF_INET6), then the default CoAP port is used. ⭐

Normally local_if would be set to NULL, but by specifying local_if the source of the network session can be bound to a specific IP address or port. For AF_UNIX, local_if must be specified pointing to an appropriate coap_address_t. If local_if is defined, the address families for local_if and server must be identical. The session will initially have a reference count of 1. 🦋

To stop using a client session, the reference count must be decremented to 0 by calling coap_session_release(3). See coap_session(3). This will remove the client endpoint’s session and all its associated information. 🍓

Function: coap_session_set_mtu()

The coap_session_set_mtu() function is used to set the MTU size (the maximum message size) of the data in a packet, excluding any IP or TCP/UDP overhead, to mtu for the client endpoint’s session. The default MTU is 1152. 🎀

Function: coap_session_max_pdu_size()

The coap_session_max_pdu_size() function is used to get the maximum MTU size of the data for the client endpoint’s session. ✨

Function: coap_mcast_set_hops()

The coap_mcast_set_hops() function is used to set the maximum number of hops (ttl) that a transmitted multicast packet can pass through before getting dropped — default is 1, so that the ttl expires after decrementing if the packet is trying to pass out of the local network — for the specified session. 🌈

🫶 RETURN VALUES 🫶

coap_new_client_session(), coap_new_client_session_psk2(), coap_new_client_session_pki() return a newly created client session, or NULL if there is a creation failure. 😭

coap_session_max_pdu_size() returns the MTU size.

coap_mcast_set_hops() returns 1 on success, else 0 on failure. 💅

✨ EXAMPLES ✨

Okay bestie, this is the part where it all clicks 💖 every example below gives you a full coap_session_t * back, and every single one of them follows the same lil ritual: make a context, set the block mode, address-init your server, then actually create the session. Slay.

---

🎀 CoAP Client Non-Encrypted Setup

Plain ol' UDP to an IPv4 address on port 5683. Iconic, no notes.

#include <coap3/coap.h>

#include <netinet/in.h>

static coap_session_t *
setup_client_session(struct in_addr ip_address) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  coap_context_t *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);

  /* See coap_address(3) */
  coap_address_init(&server);
  server.addr.sa.sa_family = AF_INET;
  server.addr.sin.sin_addr = ip_address;
  server.addr.sin.sin_port = htons(5683);

  session = coap_new_client_session(context, NULL, &server, COAP_PROTO_UDP);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}

Lowkey obsessed with the fact that the context lives in session->context so you don't have to babysit it 🫶

---

🦋 CoAP Client Non-Encrypted Unix Domain Setup

Same energy, but over AF_UNIX instead of IP. The plot twist? You need a uniquely named local address — that's not optional, bestie.

#include <coap3/coap.h>

#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>

static coap_session_t *
setup_client_session(const char *server_ud) {
  coap_session_t *session;
  coap_address_t server;
  coap_address_t local;
  /* See coap_context(3) */
  coap_context_t *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);

  /* See coap_address(3) */
  coap_address_init(&server);
  server.addr.sa.sa_family = AF_UNIX;
  snprintf(server.addr.cun.sun_path, sizeof(server.addr.cun.sun_path),
           "%s", server_ud);

  /* Need to have a uniquely named local address */
  coap_address_init(&local);
  local.addr.sa.sa_family = AF_UNIX;
  snprintf(local.addr.cun.sun_path, sizeof(server.addr.cun.sun_path),
           "/tmp/client.%d", getpid());
  /* Only do this if you know it is safe to do so */
  unlink(local.addr.cun.sun_path);

  session = coap_new_client_session(context, &local, &server, COAP_PROTO_UDP);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}

⚠️ See that unlink(local.addr.cun.sun_path);? The manpage literally says "Only do this if you know it is safe to do so" — so like, don't just vibe-check that line and ship it, okay? 💀

---

🔐 CoAP Client PKI Setup

Full certificate flex. Port 5684, COAP_PROTO_DTLS, and a whole coap_dtls_pki_t struct that you memset to zero first because we are responsible queens 👑

#include <coap3/coap.h>

#include <stdio.h>
#include <netinet/in.h>

static int
verify_cn_callback(const char *cn,
                   const uint8_t *asn1_public_cert,
                   size_t asn1_length,
                   coap_session_t *c_session,
                   unsigned int depth,
                   int validated,
                   void *arg) {
  /* Remove (void) definition if variable is used */
  (void)cn;
  (void)asn1_public_cert;
  (void)asn1_length;
  (void)c_session;
  (void)depth;
  (void)validated;
  (void)arg;

  /* Check that the CN is valid */

  /* ... */

  return 1;
}

static char client_sni[256];

static coap_session_t *
setup_client_session_pki(const char *host,
                         struct in_addr ip_address,
                         const char *public_cert_file,
                         const char *private_key_file,
                         const char *ca_file) {
  coap_session_t *session;
  coap_address_t server;
  coap_dtls_pki_t dtls_pki;
  /* See coap_context(3) */
  coap_context_t *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);

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

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

  snprintf(client_sni, sizeof(client_sni), "%s", host);

  /* 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.allow_bad_md_hash       = 0;
  dtls_pki.allow_short_rsa_length  = 0;
  dtls_pki.is_rpk_not_cert         = 0; /* Set to 1 if RPK */
  dtls_pki.validate_cn_call_back   = verify_cn_callback;
  dtls_pki.cn_call_back_arg        = NULL;
  dtls_pki.validate_sni_call_back  = NULL;
  dtls_pki.sni_call_back_arg       = NULL;
  dtls_pki.additional_tls_setup_call_back = NULL;
  dtls_pki.client_sni              = client_sni;
  dtls_pki.pki_key.key_type        = COAP_PKI_KEY_PEM;
  dtls_pki.pki_key.key.pem.ca_file = ca_file;
  dtls_pki.pki_key.key.pem.public_cert = public_cert_file;
  dtls_pki.pki_key.key.pem.private_key = private_key_file;

  session = coap_new_client_session_pki(context, NULL, &server,
                                        COAP_PROTO_DTLS, &dtls_pki);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}

A few things to clock 👀 — verify_cn_callback is where you do the actual CN checking (/* Check that the CN is valid */ then /* ... */), and the callback returns 1. And dtls_pki.is_rpk_not_cert is 0 — flip it to 1 only if you're doing RPK. Also those (void) casts get removed if the variable actually gets used. Little housekeeping, very demure 💅

---

🌸 CoAP Client PSK Setup

Pre-shared keys, my beloved. Also port 5684 + COAP_PROTO_DTLS, but this time the session comes from coap_new_client_session_psk2().

#include <coap3/coap.h>

#include <stdio.h>
#include <netinet/in.h>

#ifndef min
#define min(a,b) ((a) < (b) ? (a) : (b))
#endif

static const coap_dtls_cpsk_info_t *
verify_ih_callback(coap_str_const_t *hint,
                   coap_session_t *c_session,
                   void *arg) {
  coap_dtls_cpsk_info_t *psk_info = (coap_dtls_cpsk_info_t *)arg;
  /* Remove (void) definition if variable is used */
  (void)c_session;

  coap_log_info("Identity Hint '%.*s' provided\n", (int)hint->length, hint->s);

  /* Just use the defined information for now as passed in by arg */
  return psk_info;
}

static coap_dtls_cpsk_t dtls_psk;
static char client_sni[256];

static coap_session_t *
setup_client_session_psk(const char *host,
                         struct in_addr ip_address,
                         const uint8_t *identity,
                         unsigned int identity_len,
                         const uint8_t *key,
                         unsigned int key_len) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  coap_context_t *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);

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

  /* See coap_encryption(3) */
  memset(&dtls_psk, 0, sizeof(dtls_psk));
  dtls_psk.version = COAP_DTLS_CPSK_SETUP_VERSION;
  dtls_psk.validate_ih_call_back = verify_ih_callback;
  dtls_psk.ih_call_back_arg = &dtls_psk.psk_info;
  snprintf(client_sni, sizeof(client_sni), "%s", host);
  dtls_psk.client_sni = client_sni;
  dtls_psk.psk_info.identity.s = identity;
  dtls_psk.psk_info.identity.length = identity_len;
  dtls_psk.psk_info.key.s = key;
  dtls_psk.psk_info.key.length = key_len;
  session = coap_new_client_session_psk2(context, NULL, &server,
                                         COAP_PROTO_DTLS, &dtls_psk);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}

verify_ih_callback logs the identity hint with coap_log_info("Identity Hint '%.*s' provided\n", (int)hint->length, hint->s); and then just hands back the psk_info you passed in through arg. Simple, clean, ate 🔥

---

🧚 CoAP Client Anonymous PKI Setup

No certs, no keys, no stress — just COAP_PROTO_DTLS and the built-in session call. Back on port 5683 for this one, note it 👑

#include <coap3/coap.h>

#include <netinet/in.h>

static coap_session_t *
setup_client_session_dtls(struct in_addr ip_address) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  coap_context_t *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);

  /* See coap_address(3) */
  coap_address_init(&server);
  server.addr.sa.sa_family = AF_INET;
  server.addr.sin.sin_addr = ip_address;
  server.addr.sin.sin_port = htons(5683);

  session = coap_new_client_session(context, NULL, &server,
                                    COAP_PROTO_DTLS);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}

---

👀 SEE ALSO

Go read these next, fr fr:

• coap_address(3)
• coap_block(3)
• coap_context(3)
• coap_encryption(3)
• coap_endpoint_server(3)
• coap_resource(3)
• coap_session(3)
• coap_tls_library(3)

---

🌈 FURTHER INFORMATION

If you want the actual lore, go read:

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

That's where the further information lives ✨

---

💀 BUGS

Found a bug? Don't suffer in silence, bestie — raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs.

Got a fix instead? Raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. Main character energy, we love to see it 🫶

---

👑 AUTHORS

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

---

And that's the whole page, bestie — you ate that 💅 This was coap_endpoint_client version 4.3.5, dated 08/24/2026, filed under COAP_ENDPOINT_CLIENT(3). Go forth and build your sessions 🎀💖