libcoap  4.3.0rc1
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 
19 #include "coap2/coap_io.h"
20 #include "coap2/coap_time.h"
21 #include "coap2/pdu.h"
22 #include "coap2/uthash.h"
23 #include "coap2/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 
42 typedef uint8_t coap_session_type_t;
46 #define COAP_SESSION_TYPE_CLIENT 1
47 #define COAP_SESSION_TYPE_SERVER 2
48 #define COAP_SESSION_TYPE_HELLO 3
50 typedef uint8_t coap_session_state_t;
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  size_t tls_overhead;
66  size_t mtu;
70  int ifindex;
74  void *tls;
75  uint16_t tx_mid;
76  uint8_t con_active;
83  size_t partial_write;
84  uint8_t read_header[8];
85  size_t partial_read;
121  void *app;
122  unsigned int max_retransmit;
125  unsigned int dtls_timeout_count;
127  uint8_t block_mode;
128  uint64_t tx_token;
130 
138 
147 
153 
160 
168 
175 
182 
190 void coap_session_set_mtu(coap_session_t *session, unsigned mtu);
191 
199 
210  struct coap_context_t *ctx,
211  const coap_address_t *local_if,
212  const coap_address_t *server,
213  coap_proto_t proto
214 );
215 
229  struct coap_context_t *ctx,
230  const coap_address_t *local_if,
231  const coap_address_t *server,
232  coap_proto_t proto,
233  const char *identity,
234  const uint8_t *key,
235  unsigned key_len
236 );
237 
254  struct coap_context_t *ctx,
255  const coap_address_t *local_if,
256  const coap_address_t *server,
257  coap_proto_t proto,
258  struct coap_dtls_cpsk_t *setup_data
259 );
260 
272  const struct coap_bin_const_t *psk_hint);
273 
285  const struct coap_bin_const_t *psk_key);
286 
303  struct coap_context_t *ctx,
304  const coap_address_t *local_if,
305  const coap_address_t *server,
306  coap_proto_t proto,
307  struct coap_dtls_pki_t *setup_data
308 );
309 
318  struct coap_context_t *ctx,
319  coap_endpoint_t *ep
320 );
321 
335  const uint8_t *data, size_t datalen);
336 
351  const uint8_t *data, size_t datalen);
352 
365 
374 void coap_session_init_token(coap_session_t *session, size_t length,
375  const uint8_t *token);
376 
385 void coap_session_new_token(coap_session_t *session, size_t *length,
386  uint8_t *token);
387 
395 const char *coap_session_str(const coap_session_t *session);
396 
397 ssize_t
399  struct coap_queue_t *node);
400 
409 coap_endpoint_t *coap_new_endpoint(struct coap_context_t *context, const coap_address_t *listen_addr, coap_proto_t proto);
410 
418 void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu);
419 
421 
422 
430 const char *coap_endpoint_str(const coap_endpoint_t *endpoint);
431 
442  const struct coap_packet_t *packet, coap_tick_t now);
443 
456  coap_tick_t now);
457 
459  const struct coap_address_t *remote_addr, int ifindex);
460 
463 
479 #define COAP_DEFAULT_ACK_TIMEOUT ((coap_fixed_point_t){2,0})
480 
488 #define COAP_DEFAULT_ACK_RANDOM_FACTOR ((coap_fixed_point_t){1,500})
489 
496 #define COAP_DEFAULT_MAX_RETRANSMIT 4
497 
503 #define COAP_DEFAULT_NSTART 1
504 
511 #define COAP_MAX_TRANSMIT_SPAN(s) \
512  ((s->ack_timeout.integer_part * 1000 + s->ack_timeout.fractional_part) * \
513  ((1 << (s->max_retransmit)) -1) * \
514  (s->ack_random_factor.integer_part * 1000 + \
515  s->ack_random_factor.fractional_part) \
516  / 1000000)
517 
524 #define COAP_MAX_TRANSMIT_WAIT(s) \
525  ((s->ack_timeout.integer_part * 1000 + s->ack_timeout.fractional_part) * \
526  ((1 << (s->max_retransmit + 1)) -1) * \
527  (s->ack_random_factor.integer_part * 1000 + \
528  s->ack_random_factor.fractional_part) \
529  / 1000000)
530 
535 #define COAP_MAX_LATENCY 100
536 
543 #define COAP_PROCESSING_DELAY(s) \
544  ((s->ack_timeout.integer_part * 1000 + s->ack_timeout.fractional_part + 500) \
545  / 1000)
546 
553 #define COAP_MAX_RTT(s) \
554  ((2 * COAP_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))
555 
562 #define COAP_EXCHANGE_LIFETIME(s) \
563  (COAP_MAX_TRANSMIT_SPAN(s) + (2 * COAP_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))
564 
571 #define COAP_NON_LIFETIME(s) \
572  (COAP_MAX_TRANSMIT_SPAN(s) + COAP_MAX_LATENCY)
573 
586  unsigned int value);
587 
599  coap_fixed_point_t value);
600 
612  coap_fixed_point_t value);
613 
624 
636 
648 
656 
657 #define SESSIONS_ADD(e, obj) \
658  HASH_ADD(hh, (e), addr_hash, sizeof((obj)->addr_hash), (obj))
659 
660 #define SESSIONS_DELETE(e, obj) \
661  HASH_DELETE(hh, (e), (obj))
662 
663 #define SESSIONS_ITER(e, el, rtmp) \
664  HASH_ITER(hh, (e), el, rtmp)
665 
666 #define SESSIONS_ITER_SAFE(e, el, rtmp) \
667 for ((el) = (e); (el) && ((rtmp) = (el)->hh.next, 1); (el) = (rtmp))
668 
669 #define SESSIONS_FIND(e, k, res) { \
670  HASH_FIND(hh, (e), &(k), sizeof(k), (res)); \
671  }
672 
673 #endif /* COAP_SESSION_H */
COAP forward definitions.
coap_nack_reason_t
Definition: coap_io.h:223
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:310
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)
coap_mid_t coap_session_send_ping(coap_session_t *session)
Send a ping message for the session.
Definition: coap_session.c:379
void coap_session_set_mtu(coap_session_t *session, unsigned mtu)
Set the session MTU.
Definition: coap_session.c:263
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:349
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:914
size_t coap_session_max_pdu_size(const coap_session_t *session)
Get maximum acceptable PDU size.
Definition: coap_session.c:242
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:275
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).
void coap_session_init_token(coap_session_t *session, size_t length, const uint8_t *token)
Initializes the token value to use as a starting point.
void coap_session_new_token(coap_session_t *session, size_t *length, uint8_t *token)
Creates a new token for use.
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.
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:941
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:397
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:720
void coap_session_free(coap_session_t *session)
Definition: coap_session.c:223
void coap_session_mfree(coap_session_t *session)
Definition: coap_session.c:157
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:454
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:899
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:296
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:692
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.
int coap_mid_t
coap_mid_t is used to store the CoAP Message ID of a CoAP PDU.
Definition: pdu.h:244
uint8_t coap_proto_t
Definition: pdu.h:345
Only used for servers for hashing incoming packets.
Definition: coap_io.h:52
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:150
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 to hold large body (many blocks) client receive information.
Structure to hold large body (many blocks) server receive information.
Structure to hold large body (many blocks) transmission information.
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:37
coap_session_t * session
the CoAP session
Definition: net.h:43
coap_pdu_t * pdu
the CoAP PDU to send
Definition: net.h:45
coap_tick_t last_pong
Definition: coap_session.h:90
coap_lg_xmit_t * lg_xmit
list of large transmissions
Definition: coap_session.h:80
unsigned int dtls_timeout_count
dtls setup retry counter
Definition: coap_session.h:125
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:103
coap_endpoint_t * endpoint
session's endpoint
Definition: coap_session.h:72
coap_tick_t last_rx_tx
Definition: coap_session.h:87
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:122
coap_pdu_t * partial_pdu
incomplete incoming pdu
Definition: coap_session.h:86
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:94
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
uint64_t tx_token
Next token number to use.
Definition: coap_session.h:128
uint8_t block_mode
Zero or more COAP_BLOCK_ or'd options.
Definition: coap_session.h:127
uint8_t read_header[8]
storage space for header of incoming message header
Definition: coap_session.h:84
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:112
coap_dtls_cpsk_t cpsk_setup_data
client provided PSK initial setup data
Definition: coap_session.h:92
struct coap_queue_t * delayqueue
list of delayed messages waiting to be sent
Definition: coap_session.h:79
size_t mtu
path or CSM mtu
Definition: coap_session.h:66
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:85
int dtls_event
Tracking any (D)TLS events on this sesison.
Definition: coap_session.h:126
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:124
uint8_t con_active
Active CON request sent.
Definition: coap_session.h:76
size_t tls_overhead
overhead of TLS layer
Definition: coap_session.h:65
void * app
application-specific data
Definition: coap_session.h:121
coap_mid_t last_ping_mid
the last keepalive message id that was used in this session
Definition: coap_session.h:78
coap_lg_srcv_t * lg_srcv
Server list of expected large receives.
Definition: coap_session.h:82
coap_tick_t last_ping
Definition: coap_session.h:89
coap_lg_crcv_t * lg_crcv
Client list of expected large receives.
Definition: coap_session.h:81
coap_fixed_point_t ack_timeout
timeout waiting for ack (default 2 secs)
Definition: coap_session.h:123
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:88
size_t partial_write
if > 0 indicates number of bytes already written from the pdu at the head of sendqueue
Definition: coap_session.h:83
coap_addr_hash_t addr_hash
Address hash for server incoming packets.
Definition: coap_session.h:67
coap_tick_t csm_tx
Definition: coap_session.h:91
int ifindex
interface index
Definition: coap_session.h:70