'\" t
.\"     Title: coap_session
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/14/2022
.\"    Manual: libcoap Manual
.\"    Source: coap_session 4.2.1
.\"  Language: English
.\"
.TH "COAP_SESSION" "3" "05/14/2022" "coap_session 4\&.2\&.1" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_session, coap_new_client_session, coap_new_client_session_psk, coap_new_client_session_pki, coap_session_reference, coap_session_release, coap_session_set_mtu, coap_session_max_pdu_size, coap_session_str \- Work with CoAP sessions
.SH "SYNOPSIS"
.sp
\fB#include <coap2/coap\&.h>\fR
.sp
\fBcoap_session_t *coap_new_client_session(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const coap_address_t *\fR\fB\fIlocal_if\fR\fR\fB, const coap_address_t *\fR\fB\fIserver\fR\fR\fB, coap_proto_t \fR\fB\fIproto\fR\fR\fB);\fR
.sp
\fBcoap_session_t *coap_new_client_session_psk(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const coap_address_t *\fR\fB\fIlocal_if\fR\fR\fB, const coap_address_t *\fR\fB\fIserver\fR\fR\fB, coap_proto_t \fR\fB\fIproto\fR\fR\fB, const char *\fR\fB\fIidentity\fR\fR\fB, const uint8_t *\fR\fB\fIkey\fR\fR\fB, unsigned \fR\fB\fIkey_len\fR\fR\fB);\fR
.sp
\fBcoap_session_t *coap_new_client_session_pki(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, const coap_address_t *\fR\fB\fIlocal_if\fR\fR\fB, const coap_address_t *\fR\fB\fIserver\fR\fR\fB, coap_proto_t \fR\fB\fIproto\fR\fR\fB, coap_dtls_pki_t *\fR\fB\fIsetup_data\fR\fR\fB);\fR
.sp
\fBcoap_session_t *coap_session_reference(coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
\fBvoid coap_session_release(coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
\fBvoid coap_session_set_mtu(coap_session_t *\fR\fB\fIsession\fR\fR\fB, unsigned \fR\fB\fImtu\fR\fR\fB);\fR
.sp
\fBsize_t coap_session_max_pdu_size(coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
\fBvoid coap_session_set_app_data(coap_session_t *\fR\fB\fIsession\fR\fR\fB, void *\fR\fB\fIdata\fR\fR\fB);\fR
.sp
\fBvoid *coap_session_get_app_data(const coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
\fBconst char *coap_session_str(const coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&.
.SH "DESCRIPTION"
.sp
This man page focuses on the CoAP Session\&.
.sp
The CoAP stack\(cqs 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\&.
.sp
A CoAP Session maintains the state of an ongoing connection between a Client and Server which is stored in a coap_session_t Session object\&.
.sp
The Session network traffic can be encrypted or un\-encrypted if there is an underlying TLS library\&.
.sp
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\&.
.sp
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\&.
.sp
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\&.
.sp
In principle the set\-up sequence for CoAP Servers looks like (see coap_context(3) for further information on the functions)
.sp
.if n \{\
.RS 4
.\}
.nf
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()
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.sp
In principle the set\-up sequence for CoAP Clients looks like
.sp
.if n \{\
.RS 4
.\}
.nf
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()
.fi
.if n \{\
.RE
.\}
.sp
Multiple client sessions are supported per Context\&.
.sp
Different CoAP protocols can be defined for \fIproto\fR \- the current supported list is:
.sp
.if n \{\
.RS 4
.\}
.nf
COAP_PROTO_UDP
COAP_PROTO_DTLS
COAP_PROTO_TCP
COAP_PROTO_TLS
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_new_client_session\fR() function initiates a new client session associated with \fIcontext\fR to the specified \fIserver\fR using the CoAP protocol \fIproto\fR\&. If the port is not specified in \fIserver\fR, then the default CoAP port is used\&. Normally \fIlocal_if\fR would be set to NULL, but by specifying \fIlocal_if\fR 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\&.
.sp
The \fBcoap_new_client_session_pki\fR() function, for a specific \fIcontext\fR, is used to configure the TLS context using the \fIsetup_data\fR variables as defined in the coap_dtls_pki_t structure \- see \fBcoap_encrytion\fR(3)\&. The session will initially have a reference count of 1\&.
.sp
The \fBcoap_new_client_session_psk\fR() function, for a specific \fIcontext\fR, is used to configure the TLS context using the client \fIidentity\fR, Pre\-Shared Key \fIkey\fR with length \fIkey_len\fR\&. All 3 parameters must be defined, NULL is not valid\&. An empty string is not valid for \fIidentity\fR\&. \fIkey_len\fR must be greater than 0\&. This function also includes the \fIserver\fR to connect to, optionally the local interface \fIlocal_if\fR to bind to and the CoAP protocol \fIproto\fR to use\&. The session will initially have a reference count of 1\&.
.sp
The \fBcoap_session_reference\fR() is used to increment the reference count of the \fIsession\fR\&. Incrementing the reference count by an application means that the library will not inadvertently remove the session when it has finished processing the session\&.
.sp
The \fBcoap_session_release\fR() function must be used to decrement the \fIsession\fR reference count, which when it gets to 0, will free off the session if this is a Client, which then clears all entries from the receive queue and send queue\&. If the reference count goes to 0 for a Server, then the \fIsession\fR is added to a free pool ready for subsequent re\-use\&. If the Server \fIsession\fR is not used for 5 minutes, then it will get completely freed off\&.
.sp
The \fBcoap_sesson_set_default_mtu\fR() 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 \fImtu\fR for the \fIsession\fR\&.
.sp
The \fBcoap_session_max_pdu_size\fR() funcition is used to get the maximum MTU size of the data for the \fIsession\fR\&.
.sp
The \fBcoap_session_set_app_data\fR() funstion is used to define a \fIdata\fR pointer for the \fIsession\fR which can then be retieved at a later date\&.
.sp
The \fBcoap_session_get_app_data\fR() function is used to retrieve the data pointer previously defined by \fBcoap_session_set_app_data\fR()\&.
.sp
The \fBcoap_session_str\fR() function is used to get a string containing the information about the \fIsession\fR\&.
.SH "RETURN VALUES"
.sp
\fBcoap_new_client_session\fR(), \fBcoap_new_client_session_psk\fR(), \fBcoap_new_client_session_pki\fR() functions returns a newly created client session or NULL if there is a creation failure\&.
.sp
\fBcoap_session_reference\fR() function returns a pointer to the session\&.
.sp
\fBcoap_session_get_app_data\fR() function return a previously defined pointer\&.
.sp
\fBcoap_session_max_pdu_size\fR() function returns the MTU size\&.
.sp
\fBcoap_session_str\fR() function returns a description string of the session\&.
.SH "EXAMPLES"
.sp
\fBCoAP Client Non\-Encrypted Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap2/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;

  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;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBCoAP Client PKI Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap2/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 *session,
                   unsigned depth,
                   int 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;

  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\&.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        = 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\&.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;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBCoAP Client PSK Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap2/coap\&.h>

#include <netinet/in\&.h>

static coap_session_t *
setup_client_session_psk (struct in_addr ip_address,
                          const char *identity,
                          const uint8_t *key,
                          unsigned 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;

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

  session = coap_new_client_session_psk(context, NULL, &server,
                                        COAP_PROTO_DTLS, identity, key, key_len);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session\->context */
  return session;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBCoAP Client Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap2/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;

  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;
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_context\fR(3), \fBcoap_resource\fR(3), \fBcoap_encryption\fR(3) and \fBcoap_tls_library\fR(3)
.SH "FURTHER INFORMATION"
.sp
See "RFC7252: The Constrained Application Protocol (CoAP)" for further information\&.
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>