Provided by: libcoap3t64_4.3.4-1.1build4_amd64 
NAME
coap_endpoint_server, coap_context_set_pki, coap_context_set_pki_root_cas,
coap_context_set_psk2, coap_new_endpoint, coap_free_endpoint,
coap_endpoint_set_default_mtu, coap_join_mcast_group_intf, coap_mcast_per_resource - Work
with CoAP server endpoints
SYNOPSIS
#include <coap3/coap.h>
int coap_context_set_pki(coap_context_t *context, const coap_dtls_pki_t *setup_data);
int coap_context_set_pki_root_cas(coap_context_t *context, const char *ca_file, const char
*ca_dir);
int coap_context_set_psk2(coap_context_t *context, coap_dtls_spsk_t *setup_data);
coap_endpoint_t *coap_new_endpoint(coap_context_t *context, const coap_address_t
*listen_addr, coap_proto_t proto);
void coap_free_endpoint(coap_endpoint_t *endpoint);
void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu);
int coap_join_mcast_group_intf(coap_context_t *context, const char *groupname, const char
*ifname);
void coap_mcast_per_resource(coap_context_t *context);
For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls,
-lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to
get the default (D)TLS library support.
DESCRIPTION
This man page focuses on the setting up of a CoAP server endpoint. For a CoAP client
endpoint, see coap_endpoint_client(3).
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, 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
which 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 Servers, this has to be done
before the Endpoint is created.
For Servers, all the encryption information is held internally by the (D)TLS context level
and the CoAP context level as the Server is listening for new incoming traffic based on
the Endpoint definition. The (D)TLS and CoAP session will not get built until the new
traffic starts, which is done by the libcoap library.
In principle the set-up sequence for CoAP Servers looks like
coap_new_context()
coap_context_set_pki_root_cas() - if the root CAs need to be updated and using PKI
coap_context_set_pki() and/or coap_context_set_psk2() - if encryption is required
coap_new_endpoint()
Multiple endpoints can be set up per context, each listening for a new traffic flow with
different TCP/UDP protocols, (D)TLS protocols, port numbers, Unix pathnames etc. When a
new traffic flow is started, then the CoAP library will create and start a new server
session.
FUNCTIONS
Function: coap_context_set_pki()
The coap_context_set_pki() function, for a specific context, is used to configure the
(D)TLS context using the setup_data PKI variables as defined in the coap_dtls_pki_t
structure - see coap_encryption(3).
Function: coap_context_set_pki_root_cas()
The coap_context_set_pki_root_cas() function is used to define a set of root CAs to be
used instead of the default set of root CAs provided as a part of the TLS library. ca_file
points to a PEM encoded file containing the list of CAs. ca_file can be NULL. ca_dir
points to a directory containing a set of PEM encoded files containing rootCAs. ca_dir can
be NULL. One or both of ca_file and ca_dir must be set. NOTE: Some TLS libraries send the
full list of CAs added by this function during the (D)TLS session setup handshakes. To
stop this, either provide a single CA using the ca_file definition in pki_key in
setup_data variable when calling coap_context_set_pki(), or set check_common_ca to 0 in
setup_data variable. See coap_encryption(3).
Function: coap_context_set_psk2()
The coap_context_set_psk2() function is used to configure the (D)TLS context using the
setup_data PSK variables as defined in the coap_dtls_spsk_t structure - see
coap_encryption(3). This function can only be used for servers as setup_data provides a
hint, not an identity.
Function: coap_new_endpoint()
The coap_new_endpoint() function creates a new endpoint for context that is listening for
new traffic as defined in listen_addr (see coap_address_t(3)). If the address family is
AF_INET or AF_INET6, then it listens on the IP address and port number defined by
listen_addr. If the port number is 0, then the default CoAP port is used. If the address
family is AF_UNIX, then it listens on the defined unix domain path which has to be unique
per endpoint. This unique unix domain path will get deleted on clean application exit.
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.
When traffic starts to come in from a client, a server CoAP session is created associated
with this endpoint. This CoAP session is created with a reference count of 0. This means
that if the server session is not used for 5 minutes, then it will get completely freed
off. See coap_session_reference(3) and coap_session_release(3) for further information.
Function: coap_free_endpoint()
The coap_free_endpoint() function must be used to free off the endpoint. It clears out all
the sessions associated with this endpoint along with any data associated with the
sessions as well as deleting the unix domain path if the address family is AF_UNIX.
Function: coap_endpoint_set_default_mtu()
The coap_endpoint_set_default_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
endpoint. A sensible default is 1280.
Function: coap_join_mcast_group_intf()
The coap_join_mcast_group_intf() function is used to join the currently defined endpoints
that are UDP, associated with context, to the defined multicast group groupname. If ifname
is not NULL, then the multicast group is associated with this interface, otherwise the
underlying O/S will choose the first appropriate interface. When the endpoint is freed
off, the associated multicast group will be removed. The registered multicast addresses
for CoAP are 224.0.1.187, ff0x::fd (Variable-Scope) - i.e. ff02::fd (Link-Local) and
ff05::fd (Site-Local).
NOTE: multicast is not supported for address family type AF_UNIX.
Function: coap_mcast_per_resource()
The coap_mcast_per_resource() function enables mcast to be controlled on a per resource
basis giving the server application flexibility in how to respond to mcast requests. With
this enabled, this is done through additional flag definitions when setting up each
resource. See coap_resource(3).
RETURN VALUES
coap_context_set_pki(), coap_context_set_pki_root_cas() and coap_context_set_psk2() return
1 on success, 0 on failure.
coap_new_endpoint() returns a newly created endpoint or NULL if there is a creation
failure.
coap_join_mcast_group_intf() returns 0 on success, -1 on failure.
EXAMPLES
CoAP Server Non-Encrypted Setup
#include <coap3/coap.h>
static coap_context_t *
setup_server_context (void) {
coap_endpoint_t *endpoint;
coap_address_t listen_addr;
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(&listen_addr);
listen_addr.addr.sa.sa_family = AF_INET;
listen_addr.addr.sin.sin_port = htons (5683);
endpoint = coap_new_endpoint(context, &listen_addr, COAP_PROTO_UDP);
if (!endpoint) {
coap_free_context(context);
return NULL;
}
/* Initialize resources - See coap_resource(3) init_resources() example */
return context;
}
CoAP Server Non-Encrypted Unix Domain Setup
#include <coap3/coap.h>
#include <stdio.h>
#include <unistd.h>
/* This need to be unique per endpoint */
#define UNIX_DOMAIN_LISTEN_DGRAM "/tmp/server.dgram"
static coap_context_t *
setup_server_context (void) {
coap_endpoint_t *endpoint;
coap_address_t listen_addr;
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_set_unix_domain(&listen_addr,
(const uint8_t *)UNIX_DOMAIN_LISTEN_DGRAM,
strlen(UNIX_DOMAIN_LISTEN_DGRAM));
/* Only do this if you know it is safe to do so */
unlink(listen_addr.addr.cun.sun_path);
endpoint = coap_new_endpoint(context, &listen_addr, COAP_PROTO_UDP);
if (!endpoint) {
coap_free_context(context);
return NULL;
}
/* Initialize resources - See coap_resource(3) init_resources() example */
return context;
}
CoAP Server DTLS PKI Setup
#include <coap3/coap.h>
typedef struct valid_cns_t {
size_t count;
char **cn_list;
} valid_cns_t;
/*
* Common Name (CN) Callback verifier
*/
static int
verify_cn_callback(const char *cn,
const uint8_t *asn1_public_cert,
size_t asn1_length,
coap_session_t *c_session,
unsigned depth,
int validated,
void *arg
) {
valid_cns_t *valid_cn_list = (valid_cns_t*)arg;
size_t i;
/* Remove (void) definition if variable is used */
(void)asn1_public_cert;
(void)asn1_length;
(void)c_session;
(void)depth;
(void)validated;
/* Check that the CN is valid */
for (i = 0; i < valid_cn_list->count; i++) {
if (!strcasecmp(cn, valid_cn_list->cn_list[i])) {
return 1;
}
}
return 0;
}
typedef struct sni_def_t {
char* sni;
coap_dtls_key_t key;
} sni_def_t;
typedef struct valid_snis_t {
size_t count;
sni_def_t *sni_list;
} valid_snis_t;
/*
* Subject Name Identifier (SNI) callback verifier
*/
static coap_dtls_key_t *
verify_pki_sni_callback(const char *sni,
void *arg
) {
valid_snis_t *valid_sni_list = (valid_snis_t *)arg;
size_t i;
/* Check that the SNI is valid */
for (i = 0; i < valid_sni_list->count; i++) {
if (!strcasecmp(sni, valid_sni_list->sni_list[i].sni)) {
return &valid_sni_list->sni_list[i].key;
}
}
return NULL;
}
/*
* Set up PKI encryption information
*/
static coap_context_t *
setup_server_context_pki (const char *public_cert_file,
const char *private_key_file,
const char *ca_file,
valid_cns_t *valid_cn_list,
valid_snis_t *valid_sni_list
) {
coap_endpoint_t *endpoint;
coap_address_t listen_addr;
coap_dtls_pki_t dtls_pki;
coap_context_t *context;
/* See coap_tls_library(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);
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.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 = valid_cn_list;
dtls_pki.validate_sni_call_back = verify_pki_sni_callback;
dtls_pki.sni_call_back_arg = valid_sni_list;
dtls_pki.additional_tls_setup_call_back = NULL;
dtls_pki.client_sni = NULL;
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;
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;
}
CoAP Server DTLS PSK Setup
#include <coap3/coap.h>
typedef struct id_def_t {
char* id;
coap_bin_const_t key;
} id_def_t;
typedef struct valid_ids_t {
int count;
id_def_t *id_list;
} valid_ids_t;
/*
* PSK Identity Pre-Shared Key selection Callback function
*/
static const coap_bin_const_t *
verify_id_callback(coap_bin_const_t *identity,
coap_session_t *c_session,
void *arg
) {
valid_ids_t *valid_id_list = (valid_ids_t*)arg;
int i;
/* Remove (void) definition if variable is used */
(void)c_session;
/* Check that the Identity is valid */
for (i = 0; i < valid_id_list->count; i++) {
if (!strcasecmp((const char*)identity->s, valid_id_list->id_list[i].id)) {
return &valid_id_list->id_list[i].key;
}
}
return NULL;
}
typedef struct sni_psk_def_t {
char* sni;
coap_dtls_spsk_info_t psk_info;
} sni_psk_def_t;
typedef struct valid_psk_snis_t {
int count;
sni_psk_def_t *sni_list;
} valid_psk_snis_t;
/*
* PSK Subject Name Identifier (SNI) callback verifier
*/
static const coap_dtls_spsk_info_t *
verify_psk_sni_callback(const char *sni,
coap_session_t *c_session,
void *arg
) {
valid_psk_snis_t *valid_sni_list = (valid_psk_snis_t *)arg;
int i;
/* Remove (void) definition if variable is used */
(void)c_session;
/* Check that the SNI is valid */
for (i = 0; i < valid_sni_list->count; i++) {
if (!strcasecmp(sni, valid_sni_list->sni_list[i].sni)) {
return &valid_sni_list->sni_list[i].psk_info;
}
}
return NULL;
}
static coap_context_t *
setup_server_context_psk (const char *hint,
const uint8_t *key,
unsigned int key_len,
valid_ids_t *valid_id_list,
valid_psk_snis_t *valid_sni_list
) {
coap_endpoint_t *endpoint;
coap_address_t listen_addr;
coap_context_t *context;
coap_dtls_spsk_t dtls_psk;
/* See coap_tls_library(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);
memset (&dtls_psk, 0, sizeof (dtls_psk));
/* see coap_encryption(3) */
dtls_psk.version = COAP_DTLS_SPSK_SETUP_VERSION;
dtls_psk.validate_id_call_back = verify_id_callback;
dtls_psk.id_call_back_arg = valid_id_list;
dtls_psk.validate_sni_call_back = verify_psk_sni_callback;
dtls_psk.sni_call_back_arg = valid_sni_list;
dtls_psk.psk_info.hint.s = (const uint8_t*)hint;
dtls_psk.psk_info.hint.length = hint ? strlen(hint) : 0;
dtls_psk.psk_info.key.s = key;
dtls_psk.psk_info.key.length = key_len;
if (coap_context_set_psk2(context, &dtls_psk)) {
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_address(3), coap_block(3), coap_context(3), coap_encryption(3),
coap_endpoint_client(3), coap_resource(3), coap_session(3) and coap_tls_library(3)
FURTHER INFORMATION
See
"RFC7252: The Constrained Application Protocol (CoAP)"
"RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets"
for further information.
BUGS
Please report bugs on the mailing list for libcoap:
libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
https://github.com/obgm/libcoap/issues
AUTHORS
The libcoap project <libcoap-developers@lists.sourceforge.net>