'\" t
.\"     Title: coap_endpoint_server
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 06/27/2021
.\"    Manual: libcoap Manual
.\"    Source: coap_endpoint_server 4.3.0
.\"  Language: English
.\"
.TH "COAP_ENDPOINT_SERVER" "3" "06/27/2021" "coap_endpoint_server 4\&.3\&.0" "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_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 \- Work with CoAP server endpoints
.SH "SYNOPSIS"
.sp
\fB#include <coap3/coap\&.h>\fR
.sp
\fBint coap_context_set_pki(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const coap_dtls_pki_t *\fR\fB\fIsetup_data\fR\fR\fB);\fR
.sp
\fBint coap_context_set_pki_root_cas(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const char *\fR\fB\fIca_file\fR\fR\fB, const char *\fR\fB\fIca_dir\fR\fR\fB);\fR
.sp
\fBint coap_context_set_psk2(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_dtls_spsk_t *setup_data);\fR
.sp
\fBcoap_endpoint_t *coap_new_endpoint(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const coap_address_t *\fR\fB\fIlisten_addr\fR\fR\fB, coap_proto_t \fR\fB\fIproto\fR\fR\fB);\fR
.sp
\fBvoid coap_free_endpoint(coap_endpoint_t *\fR\fB\fIendpoint\fR\fR\fB);\fR
.sp
\fBvoid coap_endpoint_set_default_mtu(coap_endpoint_t *\fR\fB\fIendpoint\fR\fR\fB, unsigned \fR\fB\fImtu\fR\fR\fB);\fR
.sp
\fBint coap_join_mcast_group_intf(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const char *\fR\fB\fIgroupname\fR\fR\fB, const char *\fR\fB\fIifname\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
This man page focuses on the setting up of a CoAP server endpoint\&. For a CoAP client endpoint, see \fBcoap_endpoint_client\fR(3)\&.
.sp
The CoAP stack\(cqs 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\&.
.sp
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\&.
.sp
The Session network traffic can be encrypted or un\-encrypted if there is an underlying TLS library\&.
.sp
If TLS is going to be used for encrypting the network traffic, then the 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 Clients, this is done during the Client Session set up\&.
.sp
For Servers, all the encryption information is held internally by the TLS Context level and the CoAP Context level as the Server is listening for new incoming traffic based on the Endpoint definition\&. The TLS and CoAP session will not get built until the new traffic starts, which is done by the libcoap library\&.
.sp
In principle the set\-up sequence for CoAP Servers looks like
.sp
.if n \{\
.RS 4
.\}
.nf
coap_new_context()
coap_context_set_pki_root_cas() \- if the root CAs need to be updated and PKI
coap_context_set_pki() and/or coap_context_set_psk2() \- if encryption is required
coap_new_endpoint()
.fi
.if n \{\
.RE
.\}
.sp
Multiple endpoints can be set up per Context, each listening for a new traffic flow with different TCP/UDP protocols, TLS protocols, port numbers etc\&. When a new traffic flow is started, then the CoAP library will create and start a new server session\&.
.sp
The \fBcoap_context_set_pki\fR() function, for a specific \fIcontext\fR, is used to configure the TLS context using the \fIsetup_data\fR variables as defined in the coap_dtls_pki_t structure \- see \fBcoap_encryption\fR(3)\&.
.sp
The \fBcoap_context_set_pki_root_cas\fR() 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\&. \fIca_file\fR points to a PEM encoded file containing the list of CAs\&. \fIca_file can be NULL\&. _ca_dir\fR points to a directory containing a set of PEM encoded files containing rootCAs\&. \fIca_dir\fR can be NULL\&. One or both of \fIca_file\fR and \fIca_dir\fR must be set\&. \fBNOTE:\fR 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 \fIca_file\fR definition in \fIpki_key\fR in \fIsetup_data\fR variable when calling \fBcoap_context_set_pki\fR(), or set \fIcheck_common_ca to 0 in _setup_data\fR variable\&. See \fBcoap_encryption\fR(3)\&.
.sp
The \fBcoap_context_set_psk2\fR() function is used to configure the TLS context using the \fIsetup_data\fR variables as defined in the coap_dtls_spsk_t structure \- see \fBcoap_encryption\fR(3)\&. This function can only be used for servers as \fIsetup_data\fR provides a \fIhint\fR, not an \fIidentity\fR\&.
.sp
The \fBcoap_new_endpoint\fR() function creates a new endpoint for \fIcontext\fR that is listening for new traffic on the IP address and port number defined by \fIlisten_addr\fR\&. If the port number is 0, then the default CoAP port is used\&. Different CoAP protocols can be defined for \fIproto\fR \- the current supported list is:
.sp
.if n \{\
.RS 4
.\}
.nf
COAP_PROTO_UDP
COAP_PROTO_DTLS
COAP_PROTO_TCP
COAP_PROTO_TLS
.fi
.if n \{\
.RE
.\}
.sp
\fBcoap_tcp_is_supported\fR(), \fBcoap_dtls_is_supported\fR() and \fBcoap_tls_is_supported\fR() can be used for checking whether the underlying TCP or (D)TLS protocol support is available\&. See \fBcoap_tls_library(3)\fR for further information\&.
.sp
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\&.
.sp
The \fBcoap_free_endpoint\fR() function must be used to free off the \fIendpoint\fR\&. It clears out all the sessions associated with this endpoint\&.
.sp
The \fBcoap_endpoint_set_default_mtu\fR() 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 \fImtu\fR for the \fIendpoint\fR\&. A sensible default is 1280\&.
.sp
The \fBcoap_join_mcast_group_intf\fR() function is used to join the currently defined endpoints that are UDP, associated with \fIcontext\fR, to the defined multicast group \fIgroupname\fR\&. If \fIifname\fR 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)\&.
.SH "RETURN VALUES"
.sp
\fBcoap_context_set_pki\fR(), \fBcoap_context_set_pki_root_cas\fR() and \fBcoap_context_set_psk2\fR() functions return 1 on success, 0 on failure\&.
.sp
\fBcoap_new_endpoint\fR() function returns a newly created endpoint or NULL if there is a creation failure\&.
.sp
\fBcoap_join_mcast_group_intf\fR() returns 0 on success, \-1 on failure\&.
.SH "EXAMPLES"
.sp
\fBCoAP Server Non\-Encrypted Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#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);


  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;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBCoAP Server DTLS PKI Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#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;
  }

  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;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBCoAP Server DTLS PSK Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#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;
  }

  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;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBCoAP Client DTLS PSK Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap3/coap\&.h>

#include <stdio\&.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;
  char lhint[COAP_DTLS_HINT_LENGTH];
  /* Remove (void) definition if variable is used */
  (void)c_session;

  snprintf(lhint, sizeof(lhint), "%\&.*s", (int)hint\->length, hint\->s);
  coap_log(LOG_INFO, "Identity Hint \*(Aq%s\*(Aq provided\en", lhint);

  /* 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 *uri,
                          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;
  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);


  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;
  if (uri)
    memcpy(client_sni, uri, min(strlen(uri), sizeof(client_sni)\-1));
  else
    memcpy(client_sni, "localhost", 9);
  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;
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_block\fR(3), \fBcoap_context\fR(3), \fBcoap_encryption\fR(3), \fBcoap_endpoint_client\fR()3), \fBcoap_resource\fR(3), \fBcoap_session\fR(3) and \fBcoap_tls_library\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 or raise an issue on GitHub at https://github\&.com/obgm/libcoap/issues
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>