coap_session_internal.h

Go to the documentation of this file.

/*
 * coap_session_internal.h -- Structures, Enums & Functions that are not
 * exposed to application programming
 *
 * Copyright (C) 2010-2026 Olaf Bergmann <bergmann@tzi.org>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

 
#ifndef COAP_SESSION_INTERNAL_H_
#define COAP_SESSION_INTERNAL_H_
 
#include "coap_ws_internal.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef COAP_DEFAULT_SESSION_TIMEOUT
#define COAP_DEFAULT_SESSION_TIMEOUT 300
#endif /* !COAP_DEFAULT_SESSION_TIMEOUT */
 
#define COAP_PARTIAL_SESSION_TIMEOUT_TICKS (30 * COAP_TICKS_PER_SECOND)
#define COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS 100


struct coap_addr_hash_t {
  coap_address_t remote;       
  uint16_t lport;              
  coap_proto_t proto;          
};
 
typedef enum {
  COAP_OSCORE_B_2_NONE = 0,
  COAP_OSCORE_B_2_STEP_1,
  COAP_OSCORE_B_2_STEP_2,
  COAP_OSCORE_B_2_STEP_3,
  COAP_OSCORE_B_2_STEP_4,
  COAP_OSCORE_B_2_STEP_5,
} COAP_OSCORE_B_2_STEP;

typedef enum coap_ext_token_check_t {
  COAP_EXT_T_NOT_CHECKED = 0, 
  COAP_EXT_T_CHECKED,         
  COAP_EXT_T_CHECKING,        
} coap_ext_token_check_t;
 
#ifndef COAP_MAX_PING_FAILURES
#define COAP_MAX_PING_FAILURES 3
#endif
 
/*
 * Upper bound for PDUs queued on session->doing_first_pdu while the client
 * waits for the first exchange (OSCORE confirmation, Extended Token probe,
 * Q-Block probe, etc.). Override before including libcoap headers if needed.
 */
#ifndef COAP_DOING_FIRST_MAX_QUEUE
#define COAP_DOING_FIRST_MAX_QUEUE 4
#endif /* COAP_DOING_FIRST_MAX_QUEUE */

struct coap_session_t {
  coap_proto_t proto;               
  coap_session_type_t type;         
  coap_session_state_t state;       
  unsigned ref;                     
  size_t tls_overhead;              
  size_t mtu;                       
  size_t csm_rcv_mtu;               
  coap_addr_hash_t addr_hash;  
  UT_hash_handle hh;
  coap_addr_tuple_t addr_info;      
#if COAP_CLIENT_SUPPORT
  coap_address_t local_reconnect;   
#endif /* COAP_CLIENT_SUPPORT */
  int ifindex;                      
#if COAP_SERVER_SUPPORT
  unsigned ref_subscriptions;       
  unsigned ref_proxy_subs;          
#endif /* COAP_SERVER_SUPPORT */
  coap_socket_t sock;               
#if COAP_SERVER_SUPPORT
  coap_endpoint_t *endpoint;        
#endif /* COAP_SERVER_SUPPORT */
  coap_context_t *context;          
  void *tls;                        
  uint16_t tx_mid;                  
  uint8_t con_active;               
  uint8_t csm_block_supported;      
  coap_mid_t last_ping_mid;         
  coap_queue_t *delayqueue;         
  coap_queue_t *delayqueue_tail;    
  coap_lg_xmit_t *lg_xmit;          
#if COAP_CLIENT_SUPPORT
  coap_lg_crcv_t *lg_crcv;       
#endif /* COAP_CLIENT_SUPPORT */
#if COAP_SERVER_SUPPORT
  coap_lg_srcv_t *lg_srcv;       
#endif /* COAP_SERVER_SUPPORT */
  size_t partial_write;             
  uint8_t read_header[8];           
  size_t partial_read;              
  coap_pdu_t *partial_pdu;          
  coap_tick_t last_rx_tx;
  coap_tick_t last_tx_rst;
  coap_tick_t last_ping;
  coap_tick_t last_pong;
  coap_tick_t csm_tx;
  coap_dtls_cpsk_t cpsk_setup_data; 
  coap_bin_const_t *psk_identity;   
  coap_bin_const_t *psk_key;        
  coap_bin_const_t *psk_hint;       
  void *app_data;                     
  coap_app_data_free_callback_t app_cb; 
  coap_fixed_point_t ack_timeout;   
  coap_fixed_point_t ack_random_factor; 
  uint16_t max_retransmit;          
  uint16_t nstart;                  
  coap_fixed_point_t default_leisure; 
  uint32_t probing_rate;            
#if COAP_Q_BLOCK_SUPPORT
  uint16_t max_payloads;            
  uint16_t non_max_retransmit;      
  coap_fixed_point_t non_timeout;   
  coap_fixed_point_t non_receive_timeout;  
  coap_fixed_point_t non_probing_wait_base; 
  coap_fixed_point_t non_partial_timeout; 
#endif /* COAP_Q_BLOCK_SUPPORT */
  unsigned int dtls_timeout_count;      
  int dtls_event;                       
  uint32_t tx_rtag;               
  uint32_t block_mode;           
  uint8_t csm_bert_rem_support;  
  uint8_t csm_bert_loc_support;  
#if COAP_CLIENT_SUPPORT
  uint8_t doing_first;            
#endif /* COAP_CLIENT_SUPPORT */
  uint8_t proxy_session;        
  uint8_t delay_recursive;        
  uint8_t no_observe_cancel;      
  uint8_t csm_not_seen;           
#if COAP_OSCORE_SUPPORT
  uint8_t oscore_encryption;      
  COAP_OSCORE_B_2_STEP b_2_step;  
  oscore_recipient_ctx_t *recipient_ctx; 
  oscore_association_t *associations; 
  uint64_t oscore_r2;             
  coap_str_const_t *b_2_retransmit_token; 
#endif /* COAP_OSCORE_SUPPORT */
#if COAP_WS_SUPPORT
  coap_ws_state_t *ws;            
  coap_str_const_t *ws_host;      
#endif /* COAP_WS_SUPPORT */
#if COAP_OSCORE_SUPPORT
  uint8_t doing_b_1_2;            
#endif /* COAP_OSCORE_SUPPORT */
  volatile uint8_t max_token_checked; 
  uint8_t is_dtls13;              
#if COAP_CLIENT_SUPPORT
  uint8_t negotiated_cid;         
  uint8_t doing_send_recv;        
  uint8_t session_failed;         
  uint8_t client_initiated;       
  uint8_t retry_count;           
  coap_tick_t doing_first_timeout; 
  coap_pdu_t *doing_first_pdu;    
#endif /* COAP_CLIENT_SUPPORT */
  uint8_t no_path_abbrev;         
  coap_mid_t remote_test_mid;     
  uint32_t max_token_size;        
  uint64_t tx_token;              
  coap_bin_const_t *last_token;   
  coap_bin_const_t *echo;         
  coap_mid_t last_resp_mid;       
  coap_response_t last_con_handler_res; 
#if COAP_SERVER_SUPPORT
  coap_bin_const_t *client_cid;   
  coap_pdu_t *last_resp_pdu;      
#endif /* COAP_SERVER_SUPPORT */
#if COAP_CLIENT_SUPPORT
  coap_pdu_t *resp_pdu;           
  coap_bin_const_t *req_token;    
#endif /* COAP_CLIENT_SUPPORT */
#if COAP_PROXY_SUPPORT
  coap_proxy_entry_t *proxy_entry; 
  coap_proxy_server_list_t *server_list; 
#endif /* COAP_PROXY_SUPPORT */
  uint64_t rl_ticks_per_packet;   
  coap_tick_t last_tx;            
  uint8_t is_rate_limiting;       
  uint32_t ping_failed;           
#ifdef HAVE_LINUX_ERRQUEUE_H
  coap_str_const_t *last_data_write; 
#endif /* HAVE_LINUX_ERRQUEUE_H */
};
 
#if COAP_SERVER_SUPPORT
struct coap_endpoint_t {
  struct coap_endpoint_t *next;
  coap_context_t *context;        
  coap_proto_t proto;             
  uint16_t default_mtu;           
  coap_socket_t sock;             
  coap_address_t bind_addr;       
  coap_session_t *sessions;       
 
  void *app_data;                       
  coap_app_data_free_callback_t app_cb; 
};
#endif /* COAP_SERVER_SUPPORT */
 
coap_fixed_point_t coap_multi_fixed_fixed(coap_fixed_point_t fp1,
                                          coap_fixed_point_t fp2);
 
coap_fixed_point_t coap_multi_fixed_uint(coap_fixed_point_t fp1,
                                         uint32_t u2);
 
coap_fixed_point_t coap_add_fixed_fixed(coap_fixed_point_t fp1,
                                        coap_fixed_point_t fp2);
 
coap_fixed_point_t coap_add_fixed_uint(coap_fixed_point_t fp1,
                                       uint32_t u2);
 
coap_fixed_point_t coap_sub_fixed_uint(coap_fixed_point_t fp1,
                                       uint32_t u2);
 
coap_fixed_point_t coap_div_fixed_uint(coap_fixed_point_t fp1, uint32_t u2);
 
coap_fixed_point_t coap_get_non_timeout_random(coap_session_t *session);
 
coap_tick_t coap_get_non_timeout_random_ticks(coap_session_t *session);
 

void coap_session_send_csm(coap_session_t *session);

void coap_session_connected(coap_session_t *session);

void coap_session_disconnected_lkd(coap_session_t *session,
                                   coap_nack_reason_t reason);

coap_mid_t coap_session_send_ping_lkd(coap_session_t *session);

int coap_session_refresh_psk_hint(coap_session_t *session,
                                  const coap_bin_const_t *psk_hint);

int coap_session_refresh_psk_key(coap_session_t *session,
                                 const coap_bin_const_t *psk_key);

int coap_session_refresh_psk_identity(coap_session_t *session,
                                      const coap_bin_const_t *psk_identity);
 
#if COAP_SERVER_SUPPORT
coap_session_t *coap_new_server_session(coap_context_t *ctx,
                                        coap_endpoint_t *ep,
                                        void *extra);
#endif /* COAP_SERVER_SUPPORT */

void coap_session_establish(coap_session_t *session);

coap_session_t *coap_session_reference_lkd(coap_session_t *session);

int coap_session_set_type_client_lkd(coap_session_t *session, int report_changed);

int coap_session_set_type_server_lkd(coap_session_t *session);

void coap_session_release_lkd(coap_session_t *session);

ssize_t coap_session_send_pdu(coap_session_t *session, coap_pdu_t *pdu);
 
ssize_t coap_session_delay_pdu(coap_session_t *session, coap_pdu_t *pdu,
                               coap_queue_t *node);
 
#if COAP_SERVER_SUPPORT
coap_session_t *coap_endpoint_get_session(coap_endpoint_t *endpoint,
                                          const coap_packet_t *packet, coap_tick_t now);

coap_endpoint_t *coap_new_endpoint_lkd(coap_context_t *context, const coap_address_t *listen_addr,
                                       coap_proto_t proto);

void coap_free_endpoint_lkd(coap_endpoint_t *endpoint);
 
#endif /* COAP_SERVER_SUPPORT */

size_t coap_session_max_pdu_rcv_size(const coap_session_t *session);

size_t coap_session_max_pdu_size_lkd(const coap_session_t *session);

coap_session_t *coap_new_client_session3_lkd(coap_context_t *ctx,
                                             const coap_address_t *local_if,
                                             const coap_address_t *server,
                                             coap_proto_t proto,
                                             void *app_data,
                                             coap_app_data_free_callback_t callback,
                                             coap_str_const_t *ws_host
                                            );

coap_session_t *coap_new_client_session_pki3_lkd(coap_context_t *ctx,
                                                 const coap_address_t *local_if,
                                                 const coap_address_t *server,
                                                 coap_proto_t proto,
                                                 coap_dtls_pki_t *setup_data,
                                                 void *app_data,
                                                 coap_app_data_free_callback_t callback,
                                                 coap_str_const_t *ws_host
                                                );

coap_session_t *coap_new_client_session_psk_lkd(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
                                               );

coap_session_t *coap_new_client_session_psk3_lkd(coap_context_t *ctx,
                                                 const coap_address_t *local_if,
                                                 const coap_address_t *server,
                                                 coap_proto_t proto,
                                                 coap_dtls_cpsk_t *setup_data,
                                                 void *app_data,
                                                 coap_app_data_free_callback_t callback,
                                                 coap_str_const_t *ws_host
                                                );

int coap_session_reconnect(coap_session_t *session);

coap_session_t *coap_session_new_dtls_session(coap_session_t *session,
                                              coap_tick_t now);

void coap_session_server_keepalive_failed(coap_session_t *session);

void *coap_session_set_app_data2_lkd(coap_session_t *session, void *data,
                                     coap_app_data_free_callback_t callback);

void *coap_endpoint_set_app_data_lkd(coap_endpoint_t *endpoint, void *data,
                                     coap_app_data_free_callback_t callback);
 
void coap_session_free(coap_session_t *session);
void coap_session_mfree(coap_session_t *session);
 
void coap_read_session(coap_context_t *ctx, coap_session_t *session, coap_tick_t now);
 
void coap_connect_session(coap_session_t *session, coap_tick_t now);
 
void coap_handle_nack(coap_session_t *session,
                      coap_pdu_t *sent,
                      const coap_nack_reason_t reason,
                      const coap_mid_t mid);

void coap_session_failed(coap_session_t *session);

void coap_session_reestablished(coap_session_t *session);
 
#define COAP_SESSION_REF(s) ((s)->ref
 
/* RFC7252 */
#define COAP_ACK_TIMEOUT(s) ((s)->ack_timeout)
#define COAP_ACK_RANDOM_FACTOR(s) ((s)->ack_random_factor)
#define COAP_MAX_RETRANSMIT(s) ((s)->max_retransmit)
#define COAP_NSTART(s) ((s)->nstart)
#define COAP_DEFAULT_LEISURE(s) ((s)->default_leisure)
#define COAP_PROBING_RATE(s) ((s)->probing_rate)
/* RFC9177 */
#define COAP_MAX_PAYLOADS(s) ((s)->max_payloads)
#define COAP_NON_MAX_RETRANSMIT(s) ((s)->non_max_retransmit)
#define COAP_NON_TIMEOUT(s) ((s)->non_timeout)
#define COAP_NON_TIMEOUT_TICKS(s) \
  (COAP_NON_TIMEOUT(s).integer_part * COAP_TICKS_PER_SECOND + \
   COAP_NON_TIMEOUT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)
#define COAP_NON_RECEIVE_TIMEOUT(s) ((s)->non_receive_timeout)
#define COAP_NON_PROBING_WAIT_BASE(s) ((s)->non_probing_wait_base)
#define COAP_NON_PARTIAL_TIMEOUT(s) ((s)->non_partial_timeout)

#define COAP_DEFAULT_LEISURE_TICKS(s) \
  (COAP_DEFAULT_LEISURE(s).integer_part * COAP_TICKS_PER_SECOND + \
   COAP_DEFAULT_LEISURE(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)

#define COAP_MAX_TRANSMIT_SPAN(s) \
  (((s)->ack_timeout.integer_part * 1000 + (s)->ack_timeout.fractional_part) * \
   ((1 << ((s)->max_retransmit)) -1) * \
   ((s)->ack_random_factor.integer_part * 1000 + \
    (s)->ack_random_factor.fractional_part) \
   / 1000000)

#define COAP_MAX_TRANSMIT_WAIT(s) \
  (((s)->ack_timeout.integer_part * 1000 + (s)->ack_timeout.fractional_part) * \
   ((1 << ((s)->max_retransmit + 1)) -1) * \
   ((s)->ack_random_factor.integer_part * 1000 + \
    (s)->ack_random_factor.fractional_part) \
   / 1000000)
 
#define COAP_MAX_TRANSMIT_WAIT_TICKS(s) \
  (COAP_MAX_TRANSMIT_WAIT(s) * COAP_TICKS_PER_SECOND)

#define COAP_PROCESSING_DELAY(s) \
  (((s)->ack_timeout.integer_part * 1000 + (s)->ack_timeout.fractional_part + \
    500) / 1000)

#define COAP_MAX_RTT(s) \
  ((2 * COAP_DEFAULT_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))

#define COAP_EXCHANGE_LIFETIME(s) \
  (COAP_MAX_TRANSMIT_SPAN(s) + (2 * COAP_DEFAULT_MAX_LATENCY) + \
   COAP_PROCESSING_DELAY(s))

#define COAP_NON_LIFETIME(s) \
  (COAP_MAX_TRANSMIT_SPAN(s) + COAP_DEFAULT_MAX_LATENCY)

#define COAP_NON_RECEIVE_TIMEOUT_TICKS(s) ( \
                                            COAP_NON_RECEIVE_TIMEOUT(s).integer_part * COAP_TICKS_PER_SECOND + \
                                            COAP_NON_RECEIVE_TIMEOUT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)

#define COAP_NON_PROBING_WAIT(s) \
  coap_add_fixed_fixed(COAP_NON_PROBING_WAIT_BASE(s), \
                       COAP_NON_TIMEOUT_RANDOM(s))
 
#define COAP_NON_PROBING_WAIT_TICKS(s) \
  (COAP_NON_PROBING_WAIT(s).integer_part * COAP_TICKS_PER_SECOND + \
   COAP_NON_PROBING_WAIT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)

#define COAP_NON_PARTIAL_TIMEOUT_TICKS(s) \
  (COAP_NON_PARTIAL_TIMEOUT(s).integer_part * COAP_TICKS_PER_SECOND + \
   COAP_NON_PARTIAL_TIMEOUT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)

#define COAP_NON_TIMEOUT_RANDOM(s) \
  coap_get_non_timeout_random(s)

 
#define SESSIONS_ADD(e, obj) \
  HASH_ADD(hh, (e), addr_hash, sizeof((obj)->addr_hash), (obj))
 
#define SESSIONS_DELETE(e, obj) \
  HASH_DELETE(hh, (e), (obj))
 
#define SESSIONS_ITER(e, el, rtmp)  \
  HASH_ITER(hh, (e), el, rtmp)
 
#define SESSIONS_ITER_SAFE(e, el, rtmp) \
  for ((el) = (e); (el) && ((rtmp) = (el)->hh.next, 1); (el) = (rtmp))
 
#define SESSIONS_FIND(e, k, res) {                     \
    HASH_FIND(hh, (e), &(k), sizeof(k), (res)); \
  }
 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_SESSION_INTERNAL_H_ */