Provided by: libcoap2_4.2.1-1build1_amd64 bug

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>