1COAP_SESSION(3) libcoap Manual COAP_SESSION(3)
2
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
12 #include <coap2/coap.h>
13 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 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 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 coap_session_t *coap_session_reference(coap_session_t *session);
28 void coap_session_release(coap_session_t *session);
30 void coap_session_set_mtu(coap_session_t *session, unsigned mtu);
32 size_t coap_session_max_pdu_size(coap_session_t *session);
34 void coap_session_set_app_data(coap_session_t *session, void *data);
36 void *coap_session_get_app_data(const coap_session_t *session);
38 const char *coap_session_str(const coap_session_t *session);
40 Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
42 -lcoap-2-tinydtls depending on your (D)TLS library type.
43
45 This man page focuses on the CoAP Session.
46 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 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 The Session network traffic can be encrypted or un-encrypted if there
57 is an underlying TLS library.
58 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 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 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 In principle the set-up sequence for CoAP Servers looks like (see
81 coap_context(3) for further information on the functions)
82 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 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 In principle the set-up sequence for CoAP Clients looks like
94 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 Multiple client sessions are supported per Context.
100 Different CoAP protocols can be defined for proto - the current
102 supported list is:
103 COAP_PROTO_UDP
105 COAP_PROTO_DTLS
106 COAP_PROTO_TCP
107 COAP_PROTO_TLS
108 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 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 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 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 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 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 The coap_session_max_pdu_size() funcition is used to get the maximum
149 MTU size of the data for the session.
150 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 The coap_session_get_app_data() function is used to retrieve the data
155 pointer previously defined by coap_session_set_app_data().
156 The coap_session_str() function is used to get a string containing the
158 information about the session.
159
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 coap_session_reference() function returns a pointer to the session.
166 coap_session_get_app_data() function return a previously defined
168 pointer.
169 coap_session_max_pdu_size() function returns the MTU size.
171 coap_session_str() function returns a description string of the
173 session.
174
176 CoAP Client Non-Encrypted Setup
177 #include <coap2/coap.h>
179 #include <netinet/in.h>
181 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 if (!context)
190 return NULL;
191 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 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 CoAP Client PKI Setup
207 #include <coap2/coap.h>
209 #include <netinet/in.h>
211 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 /* ... */
224 return 1;
226 }
227 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 if (!context)
241 return NULL;
242 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 memset (&dtls_pki, 0, sizeof (dtls_pki));
249 /* 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 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 CoAP Client PSK Setup
283 #include <coap2/coap.h>
285 #include <netinet/in.h>
287 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 if (!context)
300 return NULL;
301 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 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 CoAP Client Setup
318 #include <coap2/coap.h>
320 #include <netinet/in.h>
322 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 if (!context)
331 return NULL;
332 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 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
349 coap_context(3), coap_resource(3), coap_encryption(3) and
350 coap_tls_library(3)
351
353 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
354 information.
355
357 Please report bugs on the mailing list for libcoap:
358 libcoap-developers@lists.sourceforge.net
359
361 The libcoap project <libcoap-developers@lists.sourceforge.net>
362coap_session 4.2.1 02/24/2020 COAP_SESSION(3)