Files
libcoap/man/coap_context.txt.in
T
Jon Shallow 05d30e5ef1 PKI: Make (D)TLS operation consistent across all TLS libraries
The use of the verify_peer_cert and require_peer_cert variables in the
coap_dtls_pki_t structure was giving inconsistent results across all the
TLS libraries.  This primarily was down to the large numbers of options
available to control the TLS handshakes in OpenSSL compared to the limited
control available to mbedTLS port which followed later. require_peer_cert is
not easy to control in mbedTLS as it is an implicit configuration based on how
other, not always related, items were configured.

require_peer_cert was used by the server to control whether the client could
use anonymous certificates or not.  This is now controlled by verify_peer_cert.

require_peer_cert variable has been replaced with check_common_ca, so that
the OpenSSL functionality can continue, but enable GnuTLS / mbedTLS to
produce the same results.  This allows peers to mutually authenticate (because
the peer certs are signed by the same common CA) or not which was in effect
controlled by verify_peer_cert previously.

If check_common_ca is set, then allow_self_signed is ignored.

If is_rpk_not_cert is set, then all certificate validation is ignored.

In the examples, use of the -R option unsets check_common_ca, so disables
mutual authentication support by having a common CA.  This was needed as
mbedTLS and GnuTLS only have a single trust store for CAs.

configure.ac:

Increase the number of mbed libraries to use when checking for mbedTLS.

examples/client.c:
examples/coap-rd.c:
examples/coap-server.c:

Add in -n (unset verify_peer_cert) option. In the case of coap-server and
coap-rd, make -n refer to verify_peer_cert.
Add in TLS library capabilites in usage().

Update usage() documentation as appropriate, with some changes to fit
everything into a 80 column output.

include/coap2/coap_dtls.h:
include/coap2/net.h:

Update with variable changes, and make the coap_dtls_pki_t parameter const for
the *_context_set_pki() functions.

man/coap-client.txt.in:
man/coap-rd.txt.in:
man/coap-server.txt.in:

Update documentation to reflect the examples option usage.

man/coap_context.txt.in:
man/coap_encryption.txt.in:
man/coap_session.txt.in:

Update with the new variable name and document as appropriate.

src/coap_gnutls.c
src/coap_mbedtls.c
src/coap_notls.c
src/coap_openssl.c
coap_tinydtls.c

Update to make variable usage consistent. Update logging from LOG_WARNING to
LOG_INFO where there is an override of a PKI check failure by one of the
coap_dtls_pki_t variables.

Timing window closed for TLS where the peer does not like a certificate, sends
fatal alert and closes connection.  local then fails on writing the next
handshake - but now also reads in alert and reports on it.

src/coap_io.c:

Update logging from LOG_WARNING to LOG_INFO for EPIPE or ECONNRESET errors in
coap_socket_write().

src/net.c:

Handle the const coap_dtls_pki_t parameter in coap_context_set_pki() function.
2021-02-18 16:51:32 +00:00

563 lines
17 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_pki_root_cas,
coap_context_set_psk2,
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_,
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_);*
Link with *-lcoap-@LIBCOAP_API_VERSION@*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
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_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, 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_psk2()
----
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_encryption*(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. +
*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).
The *coap_context_set_psk2*() function is used to configure the TLS context
using the _setup_data_ 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_.
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_psk2*() 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;
}
/* Initialize resources - See coap_resource(3) init_resources() example */
return context;
}
----
*CoAP Server DTLS PKI Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/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;
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;
}
----
*CoAP Server DTLS PSK Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/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;
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;
}
----
*CoAP Client DTLS PSK Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/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 '%s' provided\n", 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;
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;
}
----
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 or raise an issue on GitHub at
https://github.com/obgm/libcoap/issues
AUTHORS
-------
The libcoap project <libcoap-developers@lists.sourceforge.net>