libcoap  4.3.0beta
coap_session.h
Go to the documentation of this file.
1 /* coap_session.h -- Session management for libcoap
2 *
3 * Copyright (C) 2017 Jean-Claue Michelou <jcm@spinetix.com>
4 *
5 * This file is part of the CoAP library libcoap. Please see
6 * README for terms of use.
7 */
8 
14 #ifndef COAP_SESSION_H_
15 #define COAP_SESSION_H_
16 
17 
18 #include "coap_forward_decls.h"
19 #include "coap_io.h"
20 #include "coap_time.h"
21 #include "pdu.h"
22 #include "uthash.h"
23 #include "coap_dtls.h"
24 
29 typedef struct coap_fixed_point_t {
30  uint16_t integer_part;
31  uint16_t fractional_part;
34 
35 #define COAP_DEFAULT_SESSION_TIMEOUT 300
36 #define COAP_PARTIAL_SESSION_TIMEOUT_TICKS (30 * COAP_TICKS_PER_SECOND)
37 #define COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS 100
38 
39 #define COAP_PROTO_NOT_RELIABLE(p) ((p)==COAP_PROTO_UDP || (p)==COAP_PROTO_DTLS)
40 #define COAP_PROTO_RELIABLE(p) ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS)
41 
46 #define COAP_SESSION_TYPE_CLIENT 1
47 #define COAP_SESSION_TYPE_SERVER 2
48 #define COAP_SESSION_TYPE_HELLO 3
54 #define COAP_SESSION_STATE_NONE 0
55 #define COAP_SESSION_STATE_CONNECTING 1
56 #define COAP_SESSION_STATE_HANDSHAKE 2
57 #define COAP_SESSION_STATE_CSM 3
58 #define COAP_SESSION_STATE_ESTABLISHED 4
59 
60 typedef struct coap_session_t {
64  unsigned ref;
65  unsigned tls_overhead;
66  uint64_t mtu;
70  int ifindex;
74  void *tls;
75  uint16_t tx_mid;
80  size_t partial_write;
82  size_t partial_read;
118  void *app;
119  unsigned int max_retransmit;
122  unsigned int dtls_timeout_count;
125 
133 
142 
148 
155 
163 
170 
177 
185 void coap_session_set_mtu(coap_session_t *session, unsigned mtu);
186 
194 
205  struct coap_context_t *ctx,
206  const coap_address_t *local_if,
207  const coap_address_t *server,
208  coap_proto_t proto
209 );
210 
224  struct coap_context_t *ctx,
225  const coap_address_t *local_if,
226  const coap_address_t *server,
227  coap_proto_t proto,
228  const char *identity,
229  const uint8_t *key,
230  unsigned key_len
231 );
232 
249  struct coap_context_t *ctx,
250  const coap_address_t *local_if,
251  const coap_address_t *server,
252  coap_proto_t proto,
253  struct coap_dtls_cpsk_t *setup_data
254 );
255 
267  const struct coap_bin_const_t *psk_hint);
268 
280  const struct coap_bin_const_t *psk_key);
281 
298  struct coap_context_t *ctx,
299  const coap_address_t *local_if,
300  const coap_address_t *server,
301  coap_proto_t proto,
302  struct coap_dtls_pki_t *setup_data
303 );
304 
313  struct coap_context_t *ctx,
314  coap_endpoint_t *ep
315 );
316 
330  const uint8_t *data, size_t datalen);
331 
346  const uint8_t *data, size_t datalen);
347 
360 
361 
369 const char *coap_session_str(const coap_session_t *session);
370 
371 ssize_t
373  struct coap_queue_t *node);
374 
383 coap_endpoint_t *coap_new_endpoint(struct coap_context_t *context, const coap_address_t *listen_addr, coap_proto_t proto);
384 
392 void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu);
393 
395 
396 
404 const char *coap_endpoint_str(const coap_endpoint_t *endpoint);
405 
416  const struct coap_packet_t *packet, coap_tick_t now);
417 
430  coap_tick_t now);
431 
433  const struct coap_address_t *remote_addr, int ifindex);
434 
437 
453 #define COAP_DEFAULT_ACK_TIMEOUT ((coap_fixed_point_t){2,0})
454 
462 #define COAP_DEFAULT_ACK_RANDOM_FACTOR ((coap_fixed_point_t){1,500})
463 
470 #define COAP_DEFAULT_MAX_RETRANSMIT 4
471 
477 #define COAP_DEFAULT_NSTART 1
478 
485 #define COAP_MAX_TRANSMIT_SPAN(s) \
486  ((s->ack_timeout.integer_part * 1000 + s->ack_timeout.fractional_part) * \
487  ((1 << (s->max_retransmit)) -1) * \
488  (s->ack_random_factor.integer_part * 1000 + \
489  s->ack_random_factor.fractional_part) \
490  / 1000000)
491 
498 #define COAP_MAX_TRANSMIT_WAIT(s) \
499  ((s->ack_timeout.integer_part * 1000 + s->ack_timeout.fractional_part) * \
500  ((1 << (s->max_retransmit + 1)) -1) * \
501  (s->ack_random_factor.integer_part * 1000 + \
502  s->ack_random_factor.fractional_part) \
503  / 1000000)
504 
509 #define COAP_MAX_LATENCY 100
510 
517 #define COAP_PROCESSING_DELAY(s) \
518  ((s->ack_timeout.integer_part * 1000 + s->ack_timeout.fractional_part + 500) \
519  / 1000)
520 
527 #define COAP_MAX_RTT(s) \
528  ((2 * COAP_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))
529 
536 #define COAP_EXCHANGE_LIFETIME(s) \
537  (COAP_MAX_TRANSMIT_SPAN(s) + (2 * COAP_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))
538 
545 #define COAP_NON_LIFETIME(s) \
546  (COAP_MAX_TRANSMIT_SPAN(s) + COAP_MAX_LATENCY)
547 
560  unsigned int value);
561 
573  coap_fixed_point_t value);
574 
586  coap_fixed_point_t value);
587 
598 
610 
622 
630 
631 #define SESSIONS_ADD(e, obj) \
632  HASH_ADD(hh, (e), addr_info, sizeof((obj)->addr_info), (obj))
633 
634 #define SESSIONS_DELETE(e, obj) \
635  HASH_DELETE(hh, (e), (obj))
636 
637 #define SESSIONS_ITER(e, el, rtmp) \
638  HASH_ITER(hh, (e), el, rtmp)
639 
640 #define SESSIONS_ITER_SAFE(e, el, rtmp) \
641 for ((el) = (e); (el) && ((rtmp) = (el)->hh.next, 1); (el) = (rtmp))
642 
643 #define SESSIONS_FIND(e, k, res) { \
644  HASH_FIND(hh, (e), &(k), sizeof(k), (res)); \
645  }
646 
647 #endif /* COAP_SESSION_H */
COAP forward definitions.
coap_nack_reason_t
Definition: coap_io.h:214
void coap_session_set_max_retransmit(coap_session_t *session, unsigned int value)
Set the CoAP maximum retransmit count before failure.
Definition: coap_session.c:23
ssize_t coap_session_delay_pdu(coap_session_t *session, coap_pdu_t *pdu, struct coap_queue_t *node)
Definition: coap_session.c:277
void * coap_session_get_app_data(const coap_session_t *session)
Returns any application-specific data that has been stored with session using the function coap_sessi...
Definition: coap_session.c:102
void coap_free_endpoint(coap_endpoint_t *ep)
void coap_session_set_mtu(coap_session_t *session, unsigned mtu)
Set the session MTU.
Definition: coap_session.c:230
void coap_session_send_csm(coap_session_t *session)
Notify session transport has just connected and CSM exchange can now start.
Definition: coap_session.c:315
int coap_session_refresh_psk_key(coap_session_t *session, const struct coap_bin_const_t *psk_key)
Refresh the session's current pre-shared key (PSK).
coap_session_t * coap_session_get_by_peer(struct coap_context_t *ctx, const struct coap_address_t *remote_addr, int ifindex)
uint8_t coap_session_state_t
Definition: coap_session.h:50
coap_session_t * coap_endpoint_get_session(coap_endpoint_t *endpoint, const struct coap_packet_t *packet, coap_tick_t now)
Lookup the server session for the packet received on an endpoint, or create a new one.
coap_session_t * coap_new_client_session_psk(struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto, const char *identity, const uint8_t *key, unsigned key_len)
Creates a new client session to the designated server with PSK credentials.
Definition: coap_session.c:854
size_t coap_session_max_pdu_size(const coap_session_t *session)
Get maximum acceptable PDU size.
Definition: coap_session.c:209
ssize_t coap_session_send(coap_session_t *session, const uint8_t *data, size_t datalen)
Function interface for datagram data transmission.
Definition: coap_session.c:242
void coap_session_set_ack_random_factor(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP ack randomize factor.
Definition: coap_session.c:42
unsigned int coap_session_get_max_transmit(coap_session_t *session)
Get the CoAP maximum retransmit before failure.
Definition: coap_session.c:53
uint8_t coap_session_type_t
Definition: coap_session.h:42
coap_session_t * coap_session_reference(coap_session_t *session)
Increment reference counter on a session.
Definition: coap_session.c:68
coap_endpoint_t * coap_new_endpoint(struct coap_context_t *context, const coap_address_t *listen_addr, coap_proto_t proto)
Create a new endpoint for communicating with peers.
int coap_session_refresh_psk_hint(coap_session_t *session, const struct coap_bin_const_t *psk_hint)
Refresh the session's current Identity Hint (PSK).
coap_session_t * coap_new_client_session_pki(struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto, struct coap_dtls_pki_t *setup_data)
Creates a new client session to the designated server with PKI credentials.
Definition: coap_session.c:994
void coap_session_set_app_data(coap_session_t *session, void *data)
Stores data with the given session.
Definition: coap_session.c:96
void coap_session_release(coap_session_t *session)
Decrement reference counter on a session.
Definition: coap_session.c:74
coap_fixed_point_t coap_session_get_ack_timeout(coap_session_t *session)
Get the CoAP initial ack response timeout before the next re-transmit.
Definition: coap_session.c:58
void coap_session_set_ack_timeout(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP initial ack response timeout before the next re-transmit.
Definition: coap_session.c:32
coap_session_t * coap_new_client_session_psk2(struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto, struct coap_dtls_cpsk_t *setup_data)
Creates a new client session to the designated server with PSK credentials.
Definition: coap_session.c:881
void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu)
Set the endpoint's default MTU.
void coap_session_connected(coap_session_t *session)
Notify session that it has just connected or reconnected.
Definition: coap_session.c:363
ssize_t coap_session_send_pdu(coap_session_t *session, coap_pdu_t *pdu)
Send a pdu according to the session's protocol.
Definition: net.c:715
void coap_session_free(coap_session_t *session)
Definition: coap_session.c:190
coap_tid_t coap_session_send_ping(coap_session_t *session)
Send a ping message for the session.
Definition: coap_session.c:345
void coap_session_mfree(coap_session_t *session)
Definition: coap_session.c:156
coap_session_t * coap_new_server_session(struct coap_context_t *ctx, coap_endpoint_t *ep)
Creates a new server session for the specified endpoint.
void coap_session_disconnected(coap_session_t *session, coap_nack_reason_t reason)
Notify session that it has failed.
Definition: coap_session.c:420
coap_session_t * coap_new_client_session(struct coap_context_t *ctx, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto)
Creates a new client session to the designated server.
Definition: coap_session.c:839
ssize_t coap_session_write(coap_session_t *session, const uint8_t *data, size_t datalen)
Function interface for stream data transmission.
Definition: coap_session.c:263
struct coap_fixed_point_t coap_fixed_point_t
Abstraction of a fixed point number that can be used where necessary instead of a float.
struct coap_session_t coap_session_t
coap_fixed_point_t coap_session_get_ack_random_factor(coap_session_t *session)
Get the CoAP ack randomize factor.
Definition: coap_session.c:63
Clock Handling.
uint64_t coap_tick_t
This data type represents internal timer ticks with COAP_TICKS_PER_SECOND resolution.
Definition: coap_time.h:120
coap_session_t * coap_session_new_dtls_session(coap_session_t *session, coap_tick_t now)
Create a new DTLS session for the session.
Definition: coap_session.c:632
const char * coap_session_str(const coap_session_t *session)
Get session description.
const char * coap_endpoint_str(const coap_endpoint_t *endpoint)
Get endpoint description.
Pre-defined constants that reflect defaults for CoAP.
uint8_t coap_proto_t
Definition: pdu.h:339
int coap_tid_t
coap_tid_t is used to store CoAP transaction id, i.e.
Definition: pdu.h:244
multi-purpose address abstraction
Definition: address.h:94
CoAP binary data definition with const data.
Definition: str.h:56
The CoAP stack's global state is stored in a coap_context_t object.
Definition: net.h:141
The structure used for defining the Client PSK setup data to be used.
Definition: coap_dtls.h:339
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:245
Abstraction of virtual endpoint that can be attached to coap_context_t.
Abstraction of a fixed point number that can be used where necessary instead of a float.
Definition: coap_session.h:29
uint16_t fractional_part
Fractional part of fixed point variable 1/1000 (3 points) precision.
Definition: coap_session.h:31
uint16_t integer_part
Integer part of fixed point variable.
Definition: coap_session.h:30
structure for CoAP PDUs token, if any, follows the fixed size header, then options until payload mark...
Definition: pdu.h:287
Queue entry.
Definition: net.h:36
coap_session_t * session
the CoAP session
Definition: net.h:42
coap_pdu_t * pdu
the CoAP PDU to send
Definition: net.h:44
coap_tick_t last_pong
Definition: coap_session.h:87
unsigned int dtls_timeout_count
dtls setup retry counter
Definition: coap_session.h:122
coap_bin_const_t * psk_key
If client, this field contains the current pre-shared key for server; When this field is NULL,...
Definition: coap_session.h:100
coap_endpoint_t * endpoint
session's endpoint
Definition: coap_session.h:72
coap_tick_t last_rx_tx
Definition: coap_session.h:84
coap_socket_t sock
socket object for the session, if any
Definition: coap_session.h:71
unsigned int max_retransmit
maximum re-transmit count (default 4)
Definition: coap_session.h:119
coap_pdu_t * partial_pdu
incomplete incoming pdu
Definition: coap_session.h:83
unsigned tls_overhead
overhead of TLS layer
Definition: coap_session.h:65
coap_bin_const_t * psk_identity
If client, this field contains the current identity for server; When this field is NULL,...
Definition: coap_session.h:91
coap_session_state_t state
current state of relationaship with peer
Definition: coap_session.h:63
UT_hash_handle hh
Definition: coap_session.h:68
uint8_t read_header[8]
storage space for header of incoming message header
Definition: coap_session.h:81
coap_addr_tuple_t addr_info
key: remote/local address info
Definition: coap_session.h:69
coap_proto_t proto
protocol used
Definition: coap_session.h:61
uint16_t tx_mid
the last message id that was used in this session
Definition: coap_session.h:75
unsigned ref
reference count from queues
Definition: coap_session.h:64
coap_bin_const_t * psk_hint
If client, this field contains the server provided identity hint.
Definition: coap_session.h:109
coap_dtls_cpsk_t cpsk_setup_data
client provided PSK initial setup data
Definition: coap_session.h:89
struct coap_queue_t * delayqueue
list of delayed messages waiting to be sent
Definition: coap_session.h:79
struct coap_context_t * context
session's context
Definition: coap_session.h:73
size_t partial_read
if > 0 indicates number of bytes already read for an incoming message
Definition: coap_session.h:82
int dtls_event
Tracking any (D)TLS events on this sesison.
Definition: coap_session.h:123
void * tls
security parameters
Definition: coap_session.h:74
uint8_t csm_block_supported
CSM TCP blocks supported.
Definition: coap_session.h:77
coap_fixed_point_t ack_random_factor
ack random factor backoff (default 1.5)
Definition: coap_session.h:121
uint8_t con_active
Active CON request sent.
Definition: coap_session.h:76
void * app
application-specific data
Definition: coap_session.h:118
coap_address_t local_if
optional local interface address
Definition: coap_session.h:67
coap_tick_t last_ping
Definition: coap_session.h:86
coap_fixed_point_t ack_timeout
timeout waiting for ack (default 2 secs)
Definition: coap_session.h:120
coap_session_type_t type
client or server side socket
Definition: coap_session.h:62
coap_tick_t last_tx_rst
Definition: coap_session.h:85
uint64_t mtu
path or CSM mtu
Definition: coap_session.h:66
coap_tid_t last_ping_mid
the last keepalive message id that was used in this session
Definition: coap_session.h:78
size_t partial_write
if > 0 indicates number of bytes already written from the pdu at the head of sendqueue
Definition: coap_session.h:80
coap_tick_t csm_tx
Definition: coap_session.h:88
int ifindex
interface index
Definition: coap_session.h:70
unsigned char uint8_t
Definition: uthash.h:79