Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
COAP_CONTEXT(3)			libcoap	Manual		       COAP_CONTEXT(3)

NAME
       coap_context, coap_new_context, coap_free_context,
       coap_context_set_pki, coap_context_set_psk, coap_new_endpoint,
       coap_free_endpoint, coap_endpoint_set_default_mtu - Work	with CoAP
       contexts

SYNOPSIS
       #include	<coap2/coap.h>

       coap_context_t *coap_new_context(const coap_address_t *listen_addr);

       void coap_free_context(coap_context_t *context);

       int coap_context_set_pki(coap_context_t *context, 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_psk(coap_context_t *context, const char *hint,
       const uint8_t *key, size_t key_len);

       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);

       Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
       -lcoap-2-tinydtls depending on your (D)TLS library type.

DESCRIPTION
       This man	page focuses on	the CoAP Context.

       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.

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

       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.

       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, with the session having a reference	count
       of 1.

       For Clients, all	the encryption information can be held at the TLS
       Context and CoAP	Context	levels,	or at the TLS Session and CoAP Session
       levels. If defined at the Context level,	then when Sessions are
       created,	they 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 Servers looks like

	   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_psk()	- 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, TLS protocols, port
       numbers etc. When a new traffic flow is started,	then the CoAP library
       will create and start a new server session.

       In principle the	set-up sequence	for CoAP Clients looks like

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

       Multiple	client sessions	are supported per Context.

       The coap_new_context() function creates a new Context that is then used
       to keep all the CoAP Resources, Endpoints and Sessions information. The
       optional	listen_addr parameter, if set for a CoAP server, creates an
       Endpoint	that is	added to the context that is listening for
       un-encrypted traffic on the IP address and port number defined by
       listen_addr.

       The coap_free_context() function	must be	used to	release	the CoAP stack
       context.	It clears all entries from the receive queue and send queue
       and deletes the Resources that have been	registered with	context, and
       frees the attached Sessions and Endpoints.

       The coap_context_set_pki() function, for	a specific context, is used to
       configure the TLS context using the setup_data variables	as defined in
       the coap_dtls_pki_t structure - see *coap_encrytion(*3).

       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.

       The coap_context_set_psk() function is used to configure	the TLS
       context using the server	hint, PreShared	Key key	with length key_len.
       All parameters must be defined, NULL is not valid. An empty string is
       valid for hint. key_len must be greater than 0. This function can only
       be used for Servers as it provides a hint, not an identity.

       The coap_new_endpoint() function	creates	a new endpoint for context
       that is listening for new traffic on the	IP address and port number
       defined by listen_addr. 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

       The coap_free_endpoint()	function must be used to free off the
       endpoint. It clears out all the sessions	associated with	this endpoint.

       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.

RETURN VALUES
       coap_new_context() function returns a newly created context or NULL if
       there is	a creation failure.

       coap_context_set_pki(), coap_context_set_pki_root_cas() and
       coap_context_set_psk() functions	return 1 on success, 0 on failure.

       coap_new_endpoint() function returns a newly created endpoint or	NULL
       if there	is a creation failure.

EXAMPLES
       CoAP Server Non-Encrypted Setup

	   #include <coap2/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;

	     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;
	     }

	     /*	See coap_resource(3) */
	     init_resources(context);

	     return context;
	   }

       CoAP Server DTLS	PKI Setup

	   #include <coap2/coap.h>

	   typedef struct valid_cns_t {
	     int 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 *session,
			      unsigned depth,
			      int validated,
			      void *arg
	   ) {
	     valid_cns_t *valid_cn_list	= ( valid_cns_t*)arg;
	     int i;

	     /*	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 {
	     int count;
	     sni_def_t *sni_list;
	   } valid_snis_t;

	   /*
	    * Subject Name Identifier (SNI) callback verifier
	    */
	   static coap_dtls_key_t *
	   verify_sni_callback(const char *sni,
			       void *arg
	   ) {
	     valid_snis_t *valid_sni_list = (valid_snis_t *)arg;
	     int 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;

	     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.require_peer_cert	      =	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.validate_cn_call_back   =	verify_cn_callback;
	     dtls_pki.cn_call_back_arg	      =	valid_cn_list;
	     dtls_pki.validate_sni_call_back  =	verify_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;
	     }

	     /*	See coap_resource(3) */
	     init_resources(context);

	     return context;
	   }

       CoAP Server DTLS	PSK Setup

	   #include <coap2/coap.h>

	   static coap_context_t *
	   setup_server_context_psk (const char	*hint,
				     const uint8_t *key,
				     unsigned key_len
	   ) {
	     coap_endpoint_t *endpoint;
	     coap_address_t listen_addr;
	     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;

	     if	(coap_context_set_psk(context, hint, key, key_len)) {
	       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;
	     }

	     /*	See coap_resource(3) */
	     init_resources(context);

	     return context;
	   }

SEE ALSO
       coap_encryption(3), coap_resource(3), coap_session(3) and
       coap_tls_library(3)

FURTHER	INFORMATION
       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
       information.

BUGS
       Please report bugs on the mailing list for libcoap:
       libcoap-developers@lists.sourceforge.net

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

coap_context 4.2.1		  03/01/2021		       COAP_CONTEXT(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | FURTHER INFORMATION | BUGS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=coap_context&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help