1COAP_SESSION(3)                 libcoap Manual                 COAP_SESSION(3)
2
3
4

NAME

6       coap_session, coap_new_client_session, coap_new_client_session_psk,
7       coap_new_client_session_pki, coap_session_reference,
8       coap_session_release, coap_session_set_mtu, coap_session_max_pdu_size,
9       coap_session_str - Work with CoAP sessions
10

SYNOPSIS

12       #include <coap2/coap.h>
13
14       coap_session_t *coap_new_client_session(coap_context_t *context, const
15       coap_address_t *local_if, const coap_address_t *server, coap_proto_t
16       proto);
17
18       coap_session_t *coap_new_client_session_psk(coap_context_t *context,
19       const coap_address_t *local_if, const coap_address_t *server,
20       coap_proto_t proto, const char *identity, const uint8_t *key, unsigned
21       key_len);
22
23       coap_session_t *coap_new_client_session_pki(coap_context_t *context,
24       const coap_address_t *local_if, const coap_address_t *server,
25       coap_proto_t proto, coap_dtls_pki_t *setup_data);
26
27       coap_session_t *coap_session_reference(coap_session_t *session);
28
29       void coap_session_release(coap_session_t *session);
30
31       void coap_session_set_mtu(coap_session_t *session, unsigned mtu);
32
33       size_t coap_session_max_pdu_size(coap_session_t *session);
34
35       void coap_session_set_app_data(coap_session_t *session, void *data);
36
37       void *coap_session_get_app_data(const coap_session_t *session);
38
39       const char *coap_session_str(const coap_session_t *session);
40
41       Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
42       -lcoap-2-tinydtls depending on your (D)TLS library type.
43

DESCRIPTION

45       This man page focuses on the CoAP Session.
46
47       The CoAP stack’s global state is stored in a coap_context_t Context
48       object. Resources, Endpoints and Sessions are associated with this
49       context object. There can be more than one coap_context_t object per
50       application, it is up to the application to manage each one
51       accordingly.
52
53       A CoAP Session maintains the state of an ongoing connection between a
54       Client and Server which is stored in a coap_session_t Session object.
55
56       The Session network traffic can be encrypted or un-encrypted if there
57       is an underlying TLS library.
58
59       If TLS is going to be used for encrypting the network traffic, then the
60       TLS information for Pre-Shared Keys (PSK) or Public Key Infrastructure
61       (PKI) needs to be configured before any network traffic starts to flow.
62       For Servers, this has to be done before the Endpoint is created, for
63       Clients, this is done during the Client Session set up.
64
65       For Servers, all the encryption information is held internally by the
66       TLS Context level and the CoAP Context level as the Server is listening
67       for new incoming traffic based on the Endpoint definition. The TLS and
68       CoAP session will not get built until the new traffic starts, which is
69       done by the libcoap library, with the session having a reference count
70       of 1.
71
72       For Clients, all the encryption information can be held at the TLS
73       Context and CoAP Context levels, or at the TLS Session and CoAP Session
74       levels. If defined at the Context level, then when Sessions are
75       created, they will inherit the Context definitions, unless they have
76       separately been defined for the Session level, in which case the
77       Session version will get used. Typically the information will be
78       configured at the Session level for Clients.
79
80       In principle the set-up sequence for CoAP Servers looks like (see
81       coap_context(3) for further information on the functions)
82
83           coap_new_context()
84           coap_context_set_pki_root_cas() - if the root CAs need to be updated and PKI
85           coap_context_set_pki() and/or coap_context_set_psk() - if encryption is required
86           coap_new_endpoint()
87
88       Multiple endpoints can be set up per Context, each listening for a new
89       traffic flow with different TCP/UDP protocols, TLS protocols, port
90       numbers etc. When a new traffic flow is started, then the CoAP library
91       will create and start a new server session.
92
93       In principle the set-up sequence for CoAP Clients looks like
94
95           coap_new_context()
96           coap_context_set_pki_root_cas() if the root CAs need to be updated and PKI
97           coap_new_client_session(), coap_new_client_session_pki() or coap_new_client_session_psk()
98
99       Multiple client sessions are supported per Context.
100
101       Different CoAP protocols can be defined for proto - the current
102       supported list is:
103
104           COAP_PROTO_UDP
105           COAP_PROTO_DTLS
106           COAP_PROTO_TCP
107           COAP_PROTO_TLS
108
109       The coap_new_client_session() function initiates a new client session
110       associated with context to the specified server using the CoAP protocol
111       proto. If the port is not specified in server, then the default CoAP
112       port is used. Normally local_if would be set to NULL, but by specifying
113       local_if the source of the network session can be bound to a specific
114       IP address or port. The session will initially have a reference count
115       of 1.
116
117       The coap_new_client_session_pki() function, for a specific context, is
118       used to configure the TLS context using the setup_data variables as
119       defined in the coap_dtls_pki_t structure - see coap_encrytion(3). The
120       session will initially have a reference count of 1.
121
122       The coap_new_client_session_psk() function, for a specific context, is
123       used to configure the TLS context using the client identity, Pre-Shared
124       Key key with length key_len. All 3 parameters must be defined, NULL is
125       not valid. An empty string is not valid for identity. key_len must be
126       greater than 0. This function also includes the server to connect to,
127       optionally the local interface local_if to bind to and the CoAP
128       protocol proto to use. The session will initially have a reference
129       count of 1.
130
131       The coap_session_reference() is used to increment the reference count
132       of the session. Incrementing the reference count by an application
133       means that the library will not inadvertently remove the session when
134       it has finished processing the session.
135
136       The coap_session_release() function must be used to decrement the
137       session reference count, which when it gets to 0, will free off the
138       session if this is a Client, which then clears all entries from the
139       receive queue and send queue. If the reference count goes to 0 for a
140       Server, then the session is added to a free pool ready for subsequent
141       re-use. If the Server session is not used for 5 minutes, then it will
142       get completely freed off.
143
144       The coap_sesson_set_default_mtu() function is used to set the MTU size
145       (the maximum message size) of the data in a packet, excluding any IP or
146       TCP/UDP overhead to mtu for the session.
147
148       The coap_session_max_pdu_size() funcition is used to get the maximum
149       MTU size of the data for the session.
150
151       The coap_session_set_app_data() funstion is used to define a data
152       pointer for the session which can then be retieved at a later date.
153
154       The coap_session_get_app_data() function is used to retrieve the data
155       pointer previously defined by coap_session_set_app_data().
156
157       The coap_session_str() function is used to get a string containing the
158       information about the session.
159

RETURN VALUES

161       coap_new_client_session(), coap_new_client_session_psk(),
162       coap_new_client_session_pki() functions returns a newly created client
163       session or NULL if there is a creation failure.
164
165       coap_session_reference() function returns a pointer to the session.
166
167       coap_session_get_app_data() function return a previously defined
168       pointer.
169
170       coap_session_max_pdu_size() function returns the MTU size.
171
172       coap_session_str() function returns a description string of the
173       session.
174

EXAMPLES

176       CoAP Client Non-Encrypted Setup
177
178           #include <coap2/coap.h>
179
180           #include <netinet/in.h>
181
182           static coap_session_t *
183           setup_client_session (struct in_addr ip_address) {
184             coap_session_t *session;
185             coap_address_t server;
186             /* See coap_context(3) */
187             coap_context_t *context = coap_new_context(NULL);
188
189             if (!context)
190               return NULL;
191
192             coap_address_init(&server);
193             server.addr.sa.sa_family = AF_INET;
194             server.addr.sin.sin_addr = ip_address;
195             server.addr.sin.sin_port = htons (5683);
196
197             session = coap_new_client_session(context, NULL, &server, COAP_PROTO_UDP);
198             if (!session) {
199               coap_free_context(context);
200               return NULL;
201             }
202             /* The context is in session->context */
203             return session;
204           }
205
206       CoAP Client PKI Setup
207
208           #include <coap2/coap.h>
209
210           #include <netinet/in.h>
211
212           static int
213           verify_cn_callback(const char *cn,
214                              const uint8_t *asn1_public_cert,
215                              size_t asn1_length,
216                              coap_session_t *session,
217                              unsigned depth,
218                              int validated,
219                              void *arg
220           ) {
221             /* Check that the CN is valid */
222
223             /* ... */
224
225             return 1;
226           }
227
228           static coap_session_t *
229           setup_client_session_pki (struct in_addr ip_address,
230                                     const char *public_cert_file,
231                                     const char *private_key_file,
232                                     const char *ca_file
233           ) {
234             coap_session_t *session;
235             coap_address_t server;
236             coap_dtls_pki_t dtls_pki;
237             /* See coap_context(3) */
238             coap_context_t *context = coap_new_context(NULL);
239
240             if (!context)
241               return NULL;
242
243             coap_address_init(&server);
244             server.addr.sa.sa_family = AF_INET;
245             server.addr.sin.sin_addr = ip_address;
246             server.addr.sin.sin_port = htons (5684);
247
248             memset (&dtls_pki, 0, sizeof (dtls_pki));
249
250             /* See coap_encryption(3) */
251             dtls_pki.version                 = COAP_DTLS_PKI_SETUP_VERSION;
252             dtls_pki.verify_peer_cert        = 1;
253             dtls_pki.require_peer_cert       = 1;
254             dtls_pki.allow_self_signed       = 1;
255             dtls_pki.allow_expired_certs     = 1;
256             dtls_pki.cert_chain_validation   = 1;
257             dtls_pki.cert_chain_verify_depth = 1;
258             dtls_pki.check_cert_revocation   = 1;
259             dtls_pki.allow_no_crl            = 1;
260             dtls_pki.allow_expired_crl       = 1;
261             dtls_pki.validate_cn_call_back   = verify_cn_callback;
262             dtls_pki.cn_call_back_arg        = NULL;
263             dtls_pki.validate_sni_call_back  = NULL;
264             dtls_pki.sni_call_back_arg       = NULL;
265             dtls_pki.additional_tls_setup_call_back = NULL;
266             dtls_pki.sni                     = NULL;
267             dtls_pki.pki_key.key_type        = COAP_PKI_KEY_PEM;
268             dtls_pki.pki_key.key.pem.ca_file = ca_file;
269             dtls_pki.pki_key.key.pem.public_cert = public_cert_file;
270             dtls_pki.pki_key.key.pem.private_key = private_key_file;
271
272             session = coap_new_client_session_pki(context, NULL, &server,
273                                                   COAP_PROTO_DTLS, &dtls_pki);
274             if (!session) {
275               coap_free_context(context);
276               return NULL;
277             }
278             /* The context is in session->context */
279             return session;
280           }
281
282       CoAP Client PSK Setup
283
284           #include <coap2/coap.h>
285
286           #include <netinet/in.h>
287
288           static coap_session_t *
289           setup_client_session_psk (struct in_addr ip_address,
290                                     const char *identity,
291                                     const uint8_t *key,
292                                     unsigned key_len
293           ) {
294             coap_session_t *session;
295             coap_address_t server;
296             /* See coap_context(3) */
297             coap_context_t *context = coap_new_context(NULL);
298
299             if (!context)
300               return NULL;
301
302             coap_address_init(&server);
303             server.addr.sa.sa_family = AF_INET;
304             server.addr.sin.sin_addr = ip_address;
305             server.addr.sin.sin_port = htons (5684);
306
307             session = coap_new_client_session_psk(context, NULL, &server,
308                                                   COAP_PROTO_DTLS, identity, key, key_len);
309             if (!session) {
310               coap_free_context(context);
311               return NULL;
312             }
313             /* The context is in session->context */
314             return session;
315           }
316
317       CoAP Client Setup
318
319           #include <coap2/coap.h>
320
321           #include <netinet/in.h>
322
323           static coap_session_t *
324           setup_client_session (struct in_addr ip_address) {
325             coap_session_t *session;
326             coap_address_t server;
327             /* See coap_context(3) */
328             coap_context_t *context = coap_new_context(NULL);
329
330             if (!context)
331               return NULL;
332
333             coap_address_init(&server);
334             server.addr.sa.sa_family = AF_INET;
335             server.addr.sin.sin_addr = ip_address;
336             server.addr.sin.sin_port = htons (5683);
337
338             session = coap_new_client_session(context, NULL, &server,
339                                                   COAP_PROTO_DTLS);
340             if (!session) {
341               coap_free_context(context);
342               return NULL;
343             }
344             /* The context is in session->context */
345             return session;
346           }
347

SEE ALSO

349       coap_context(3), coap_resource(3), coap_encryption(3) and
350       coap_tls_library(3)
351

FURTHER INFORMATION

353       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
354       information.
355

BUGS

357       Please report bugs on the mailing list for libcoap:
358       libcoap-developers@lists.sourceforge.net
359

AUTHORS

361       The libcoap project <libcoap-developers@lists.sourceforge.net>
362
363
364
365coap_session 4.2.1                02/24/2020                   COAP_SESSION(3)
Impressum