mirror of
https://github.com/obgm/libcoap.git
synced 2026-11-21 06:49:05 +03:00
Part Two: man/coap_context.txt.in: Remove spurious reference to coap_endpoint_str
388 lines
12 KiB
Plaintext
388 lines
12 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc,tw=0:
|
|
|
|
coap_context(3)
|
|
=================
|
|
:doctype: manpage
|
|
:man source: coap_context
|
|
:man version: @PACKAGE_VERSION@
|
|
:man manual: libcoap Manual
|
|
|
|
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 <coap@LIBCOAP_API_VERSION@/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-@LIBCOAP_API_VERSION@*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
|
|
*-lcoap-@LIBCOAP_API_VERSION@-openssl* or
|
|
*-lcoap-@LIBCOAP_API_VERSION@-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:
|
|
|
|
[source, c]
|
|
----
|
|
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*
|
|
|
|
[source, c]
|
|
----
|
|
#include <coap@LIBCOAP_API_VERSION@/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*
|
|
[source, c]
|
|
----
|
|
#include <coap@LIBCOAP_API_VERSION@/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*
|
|
[source, c]
|
|
----
|
|
#include <coap@LIBCOAP_API_VERSION@/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>
|