// -*- mode:doc; -*-
// vim: set syntax=asciidoc,tw=0:

coap_endpoint_client(3)
=======================
:doctype: manpage
:man source:   coap_endpoint_client
:man version:  @PACKAGE_VERSION@
:man manual:   libcoap Manual

NAME
----
coap_endpoint_client,
coap_new_client_session,
coap_new_client_session_psk2,
coap_new_client_session_pki,
coap_session_set_mtu,
coap_session_max_pdu_size
- Work with CoAP client endpoints

SYNOPSIS
--------
*#include <coap@LIBCOAP_API_VERSION@/coap.h>*

*coap_session_t *coap_new_client_session(coap_context_t *_context_,
const coap_address_t *_local_if_, const coap_address_t *_server_,
coap_proto_t _proto_);*

*coap_session_t *coap_new_client_session_psk2(coap_context_t *_context_,
const coap_address_t *_local_if_, const coap_address_t *_server_, coap_proto_t
_proto_, coap_dtls_cpsk_t *_setup_data_);*

*coap_session_t *coap_new_client_session_pki(coap_context_t *_context_,
const coap_address_t *_local_if_, const coap_address_t *_server_, coap_proto_t
_proto_, coap_dtls_pki_t *_setup_data_);*

*void coap_session_set_mtu(coap_session_t *_session_, unsigned _mtu_);*

*size_t coap_session_max_pdu_size(const coap_session_t *_session_);*

For specific (D)TLS library support, link with
*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*.   Otherwise, link with
*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support.

DESCRIPTION
-----------
This man page focuses on the setting up of a CoAP client endpoint and hence
creation of a CoAP Session used to connect to a server.  For a CoAP server
endpoint, see *coap_endpoint_server*(3). There is no need to call
*coap_new_endpoint*(3) for a client as well as one of the
*coap_new_client_server**() functions.

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.

A CoAP Ssssion 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.

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 Endpoint/Session set up.

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 client endpoints 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 endpoints and hence sessions are supported per Context.

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

*coap_tcp_is_supported*(), *coap_dtls_is_supported*() and
*coap_tls_is_supported*() can be used for checking whether the underlying
TCP or (D)TLS protocol support is available.  See *coap_tls_library(3)* for
further information.

The *coap_new_client_session*() function creates a client endpoint for a
specific _context_ and initiates a new client session to the specified _server_
using the CoAP protocol
_proto_.  If the port is set to 0 in _server_, then the default CoAP
port is used.  Normally _local_if_ would be set to NULL, but by specifying
_local_if_ the source of the network session can be bound to a specific IP
address or port.  The session will initially have a reference count of 1.

The *coap_new_client_session_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 in the newly created endpoint session -
see *coap_encryption*(3). The connection is to the specified _server_ using
the CoAP protocol _proto_.  If the port is set to 0 in _server_, then the
default CoAP port is used.  Normally _local_if_ would be set to NULL, but by
specifying _local_if_ the source of the network session can be bound to a
specific IP address or port. The session will initially have a reference count
of 1.

The *coap_new_client_session_psk2*() function, for a specific _context_, is
used to configure the TLS context using the _setup_data_ variables as defined
in the coap_dtls_cpsk_t structure in the newly created endpoint session -
see *coap_encryption*(3). The connection is to the specified _server_ using
the CoAP protocol _proto_.  If the port is set to 0 in _server_, then the
default CoAP port is used.  Normally _local_if_ would be set to NULL, but by
specifying _local_if_ the source of the network session can be bound to a
specific IP address or port. The session will initially have a reference count
of 1.

To stop using a client session, the reference count must be decremented to 0
by calling *coap_session_release*(). See *coap_session*(3). This will remove
the client endpoint.

The *coap_sesson_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 client endpoint's _session_.  The default
MTU is 1152.

The *coap_session_max_pdu_size*() function is used to get the maximum MTU
size of the data for the client endpoint's _session_.

RETURN VALUES
-------------
*coap_new_client_session*(), *coap_new_client_session_psk2*(),
*coap_new_client_session_pki*() functions returns a newly created client
session or NULL if there is a creation failure.

*coap_session_max_pdu_size*() function returns the MTU size.

EXAMPLES
--------
*CoAP Client Non-Encrypted Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/coap.h>

#include <netinet/in.h>

static coap_session_t *
setup_client_session (struct in_addr ip_address) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  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 (5683);

  session = coap_new_client_session(context, NULL, &server, COAP_PROTO_UDP);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}
----

*CoAP Client PKI Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/coap.h>

#include <netinet/in.h>

static int
verify_cn_callback(const char *cn,
                   const uint8_t *asn1_public_cert,
                   size_t asn1_length,
                   coap_session_t *c_session,
                   unsigned int depth,
                   int validated,
                   void *arg
) {
  /* Remove (void) definition if variable is used */
  (void)cn;
  (void)asn1_public_cert;
  (void)asn1_length;
  (void)c_session;
  (void)depth;
  (void)validated;
  (void)arg;

  /* Check that the CN is valid */

  /* ... */

  return 1;
}

static coap_session_t *
setup_client_session_pki (struct in_addr ip_address,
                          const char *public_cert_file,
                          const char *private_key_file,
                          const char *ca_file
) {
  coap_session_t *session;
  coap_address_t server;
  coap_dtls_pki_t dtls_pki;
  /* See coap_context(3) */
  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);

  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        = NULL;
  dtls_pki.validate_sni_call_back  = NULL;
  dtls_pki.sni_call_back_arg       = NULL;
  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;

  session = coap_new_client_session_pki(context, NULL, &server,
                                        COAP_PROTO_DTLS, &dtls_pki);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}
----

*CoAP Client PSK Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/coap.h>

#include <stdio.h>
#include <netinet/in.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;
  /* Remove (void) definition if variable is used */
  (void)c_session;

  coap_log(LOG_INFO, "Identity Hint '%.*s' provided\n", (int)hint->length, hint->s);

  /* 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;
  /* See coap_context(3) */
  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;
}
----

*CoAP Client Anonymous PKI Setup*
[source, c]
----
#include <coap@LIBCOAP_API_VERSION@/coap.h>

#include <netinet/in.h>

static coap_session_t *
setup_client_session_dtls (struct in_addr ip_address) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  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 (5683);

  session = coap_new_client_session(context, NULL, &server,
                                        COAP_PROTO_DTLS);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session->context */
  return session;
}
----

SEE ALSO
--------
*coap_block*(3), *coap_context*(3), *coap_encryption*(3),
*coap_endpoint_server*(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>
