coap.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Intel Corporation
 * Copyright (c) 2021 Nordic Semiconductor
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_NET_COAP_H_
#define ZEPHYR_INCLUDE_NET_COAP_H_

 
#include <zephyr/types.h>
#include <stddef.h>
#include <stdbool.h>
#include <zephyr/net/net_ip.h>
#include <zephyr/sys/math_extras.h>
#include <zephyr/sys/slist.h>
 
#if defined(CONFIG_COAP_OSCORE)
struct coap_oscore_context;
#endif /* defined(CONFIG_COAP_OSCORE) */
 
#ifdef __cplusplus
extern "C" {
#endif

enum coap_option_num {
        COAP_OPTION_IF_MATCH = 1,        
        COAP_OPTION_URI_HOST = 3,        
        COAP_OPTION_ETAG = 4,            
        COAP_OPTION_IF_NONE_MATCH = 5,   
        COAP_OPTION_OBSERVE = 6,         
        COAP_OPTION_URI_PORT = 7,        
        COAP_OPTION_LOCATION_PATH = 8,   
        COAP_OPTION_OSCORE = 9,          
        COAP_OPTION_URI_PATH = 11,       
        COAP_OPTION_CONTENT_FORMAT = 12, 
        COAP_OPTION_MAX_AGE = 14,        
        COAP_OPTION_URI_QUERY = 15,      
        COAP_OPTION_ACCEPT = 17,         
        COAP_OPTION_LOCATION_QUERY = 20, 
        COAP_OPTION_BLOCK2 = 23,         
        COAP_OPTION_BLOCK1 = 27,         
        COAP_OPTION_SIZE2 = 28,          
        COAP_OPTION_PROXY_URI = 35,      
        COAP_OPTION_PROXY_SCHEME = 39,   
        COAP_OPTION_SIZE1 = 60,          
        COAP_OPTION_ECHO = 252,          
        COAP_OPTION_NO_RESPONSE = 258,   
        COAP_OPTION_REQUEST_TAG = 292,   
        COAP_OPTION_SIGNAL_701_MMS = 2,  
        COAP_OPTION_SIGNAL_701_BWT = 4,  
        COAP_OPTION_SIGNAL_704_ALT_ADDR = 2, 
        COAP_OPTION_SIGNAL_704_HOLD_OFF = 4, 
        COAP_OPTION_SIGNAL_705_BAD_CSM = 2   
};

enum coap_method {
        COAP_METHOD_GET = 1,     
        COAP_METHOD_POST = 2,    
        COAP_METHOD_PUT = 3,     
        COAP_METHOD_DELETE = 4,  
        COAP_METHOD_FETCH = 5,   
        COAP_METHOD_PATCH = 6,   
        COAP_METHOD_IPATCH = 7,  
};

 
#define COAP_REQUEST_MASK 0x07
 
#define COAP_VERSION_1 1U
 
#define COAP_OBSERVE_MAX_AGE 0xFFFFFF


enum coap_msgtype {
        COAP_TYPE_CON = 0,
        COAP_TYPE_NON_CON = 1,
        COAP_TYPE_ACK = 2,
        COAP_TYPE_RESET = 3
};

#define COAP_MAKE_RESPONSE_CODE(class, det) ((class << 5) | (det))

enum coap_response_code {
        COAP_RESPONSE_CODE_CREATED = COAP_MAKE_RESPONSE_CODE(2, 1),
        COAP_RESPONSE_CODE_DELETED = COAP_MAKE_RESPONSE_CODE(2, 2),
        COAP_RESPONSE_CODE_VALID = COAP_MAKE_RESPONSE_CODE(2, 3),
        COAP_RESPONSE_CODE_CHANGED = COAP_MAKE_RESPONSE_CODE(2, 4),
        COAP_RESPONSE_CODE_CONTENT = COAP_MAKE_RESPONSE_CODE(2, 5),
        COAP_RESPONSE_CODE_CONTINUE = COAP_MAKE_RESPONSE_CODE(2, 31),
        COAP_RESPONSE_CODE_BAD_REQUEST = COAP_MAKE_RESPONSE_CODE(4, 0),
        COAP_RESPONSE_CODE_UNAUTHORIZED = COAP_MAKE_RESPONSE_CODE(4, 1),
        COAP_RESPONSE_CODE_BAD_OPTION = COAP_MAKE_RESPONSE_CODE(4, 2),
        COAP_RESPONSE_CODE_FORBIDDEN = COAP_MAKE_RESPONSE_CODE(4, 3),
        COAP_RESPONSE_CODE_NOT_FOUND = COAP_MAKE_RESPONSE_CODE(4, 4),
        COAP_RESPONSE_CODE_NOT_ALLOWED = COAP_MAKE_RESPONSE_CODE(4, 5),
        COAP_RESPONSE_CODE_NOT_ACCEPTABLE = COAP_MAKE_RESPONSE_CODE(4, 6),
        COAP_RESPONSE_CODE_INCOMPLETE = COAP_MAKE_RESPONSE_CODE(4, 8),
        COAP_RESPONSE_CODE_CONFLICT = COAP_MAKE_RESPONSE_CODE(4, 9),
        COAP_RESPONSE_CODE_PRECONDITION_FAILED = COAP_MAKE_RESPONSE_CODE(4, 12),
        COAP_RESPONSE_CODE_REQUEST_TOO_LARGE = COAP_MAKE_RESPONSE_CODE(4, 13),
        COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT =
                                                COAP_MAKE_RESPONSE_CODE(4, 15),
        COAP_RESPONSE_CODE_UNPROCESSABLE_ENTITY = COAP_MAKE_RESPONSE_CODE(4, 22),
        COAP_RESPONSE_CODE_TOO_MANY_REQUESTS = COAP_MAKE_RESPONSE_CODE(4, 29),
        COAP_RESPONSE_CODE_INTERNAL_ERROR = COAP_MAKE_RESPONSE_CODE(5, 0),
        COAP_RESPONSE_CODE_NOT_IMPLEMENTED = COAP_MAKE_RESPONSE_CODE(5, 1),
        COAP_RESPONSE_CODE_BAD_GATEWAY = COAP_MAKE_RESPONSE_CODE(5, 2),
        COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE = COAP_MAKE_RESPONSE_CODE(5, 3),
        COAP_RESPONSE_CODE_GATEWAY_TIMEOUT = COAP_MAKE_RESPONSE_CODE(5, 4),
        COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED =
                                                COAP_MAKE_RESPONSE_CODE(5, 5),
        COAP_SIGNAL_CODE_CSM = COAP_MAKE_RESPONSE_CODE(7, 1),
        COAP_SIGNAL_CODE_PING = COAP_MAKE_RESPONSE_CODE(7, 2),
        COAP_SIGNAL_CODE_PONG = COAP_MAKE_RESPONSE_CODE(7, 3),
        COAP_SIGNAL_CODE_RELEASE = COAP_MAKE_RESPONSE_CODE(7, 4),
        COAP_SIGNAL_CODE_ABORT = COAP_MAKE_RESPONSE_CODE(7, 5)
};

 
#define COAP_CODE_EMPTY (0)
 
#define COAP_TOKEN_MAX_LEN 8UL
#define COAP_FIXED_HEADER_SIZE 4UL
 
/* CoAP TCP header constants (RFC 8323) */
/* Len/TKL + Code */
#define COAP_TCP_BASIC_HEADER_SIZE        (2)
/* Extended length field values */
#define COAP_TCP_HEADER_LEN_EXT_1B        (13)
#define COAP_TCP_HEADER_LEN_EXT_2B        (14)
#define COAP_TCP_HEADER_LEN_EXT_4B        (15)
/* Extended length offset values */
#define COAP_TCP_HEADER_LEN_EXT_0B_MAX    (13)
#define COAP_TCP_HEADER_LEN_EXT_1B_MAX    (269)
#define COAP_TCP_HEADER_LEN_EXT_2B_MAX    (65805)


enum coap_content_format {
        COAP_CONTENT_FORMAT_TEXT_PLAIN = 0,             
        COAP_CONTENT_FORMAT_APP_LINK_FORMAT = 40,       
        COAP_CONTENT_FORMAT_APP_XML = 41,               
        COAP_CONTENT_FORMAT_APP_OCTET_STREAM = 42,      
        COAP_CONTENT_FORMAT_APP_EXI = 47,               
        COAP_CONTENT_FORMAT_APP_JSON = 50,              
        COAP_CONTENT_FORMAT_APP_JSON_PATCH_JSON = 51,   
        COAP_CONTENT_FORMAT_APP_MERGE_PATCH_JSON = 52,  
        COAP_CONTENT_FORMAT_APP_CBOR = 60               
};

enum coap_no_response {
        COAP_NO_RESPONSE_SUPPRESS_2_XX = 0x02,
        COAP_NO_RESPONSE_SUPPRESS_4_XX = 0x08,
        COAP_NO_RESPONSE_SUPPRESS_5_XX = 0x10,
 
        COAP_NO_RESPONSE_SUPPRESS_ALL = COAP_NO_RESPONSE_SUPPRESS_2_XX |
                                        COAP_NO_RESPONSE_SUPPRESS_4_XX |
                                        COAP_NO_RESPONSE_SUPPRESS_5_XX,
};

 
/* block option helper */
#define GET_BLOCK_NUM(v)        ((v) >> 4)
#define GET_BLOCK_SIZE(v)       (((v) & 0x7))
#define GET_MORE(v)             (!!((v) & 0x08))

 
struct coap_observer;
struct coap_packet;
struct coap_pending;
struct coap_reply;
struct coap_resource;

typedef int (*coap_method_t)(struct coap_resource *resource,
                             struct coap_packet *request,
                             struct net_sockaddr *addr, net_socklen_t addr_len);

typedef void (*coap_notify_t)(struct coap_resource *resource,
                              struct coap_observer *observer);

struct coap_resource {
        coap_method_t get, post, put, del, fetch, patch, ipatch;
        coap_notify_t notify;
        const char * const *path;
        void *user_data;
        struct coap_core_metadata *metadata;
        sys_slist_t observers;
        int age;
};

struct coap_observer {
        sys_snode_t list;
        struct net_sockaddr_storage addr;
        uint8_t token[8];
        uint8_t tkl;
#if defined(CONFIG_COAP_OSCORE) || defined(__DOXYGEN__)
        struct coap_oscore_context *oscore_ctx;
#endif
};

struct coap_packet {
        uint8_t *data;    
        uint16_t offset;  
        uint16_t max_len; 
        uint8_t hdr_len;  
        uint16_t opt_len; 
        uint16_t delta;   
#if defined(CONFIG_COAP_KEEP_USER_DATA) || defined(__DOXYGEN__)
        void *user_data;
#endif
#if defined(CONFIG_COAP_OSCORE) || defined(__DOXYGEN__)
        struct coap_oscore_context *oscore_ctx;
#endif
};

struct coap_option {
        uint16_t delta;     
#if defined(CONFIG_COAP_EXTENDED_OPTIONS_LEN)
        uint16_t len;
        uint8_t value[CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE];
#else
        uint8_t len;        
        uint8_t value[12];  
#endif
};

typedef int (*coap_reply_t)(const struct coap_packet *response,
                            struct coap_reply *reply,
                            const struct net_sockaddr *from);

struct coap_transmission_parameters {
        uint32_t ack_timeout;
#if defined(CONFIG_COAP_RANDOMIZE_ACK_TIMEOUT) || defined(__DOXYGEN__)
        uint16_t ack_random_percent;
#endif /* defined(CONFIG_COAP_RANDOMIZE_ACK_TIMEOUT) */
        uint16_t coap_backoff_percent;
        uint8_t max_retransmission;
};

struct coap_pending {
        union {
                struct net_sockaddr addr; 
                struct net_sockaddr_storage addr_storage; 
        };
        int64_t t0;           
        uint32_t timeout;     
        uint16_t id;          
        uint8_t *data;        
        uint16_t len;         
        uint8_t retries;      
        struct coap_transmission_parameters params; 
};

struct coap_reply {
        coap_reply_t reply;
        void *user_data;
        int age;
        uint16_t id;
        uint8_t token[8];
        uint8_t tkl;
};

uint8_t coap_header_get_version(const struct coap_packet *cpkt);

uint8_t coap_header_get_type(const struct coap_packet *cpkt);

uint8_t coap_header_get_token(const struct coap_packet *cpkt, uint8_t *token);

uint8_t coap_header_get_code(const struct coap_packet *cpkt);

int coap_header_set_code(const struct coap_packet *cpkt, uint8_t code);

uint16_t coap_header_get_id(const struct coap_packet *cpkt);

const uint8_t *coap_packet_get_payload(const struct coap_packet *cpkt,
                                       uint16_t *len);

bool coap_uri_path_match(const char * const *path,
                         struct coap_option *options,
                         uint8_t opt_num);

int coap_packet_parse(struct coap_packet *cpkt, uint8_t *data, uint16_t len,
                      struct coap_option *options, uint8_t opt_num);

int coap_packet_set_path(struct coap_packet *cpkt, const char *path);

int coap_packet_init(struct coap_packet *cpkt, uint8_t *data, uint16_t max_len,
                     uint8_t ver, uint8_t type, uint8_t token_len,
                     const uint8_t *token, uint8_t code, uint16_t id);

int coap_ack_init(struct coap_packet *cpkt, const struct coap_packet *req,
                  uint8_t *data, uint16_t max_len, uint8_t code);

int coap_rst_init(struct coap_packet *cpkt, const struct coap_packet *req,
                  uint8_t *data, uint16_t max_len);
uint8_t *coap_next_token(void);

uint16_t coap_next_id(void);

int coap_find_options(const struct coap_packet *cpkt, uint16_t code,
                      struct coap_option *options, uint16_t veclen);

int coap_packet_append_option(struct coap_packet *cpkt, uint16_t code,
                              const uint8_t *value, uint16_t len);

int coap_packet_remove_option(struct coap_packet *cpkt, uint16_t code);

unsigned int coap_option_value_to_int(const struct coap_option *option);

int coap_append_option_int(struct coap_packet *cpkt, uint16_t code,
                           unsigned int val);

int coap_packet_append_payload_marker(struct coap_packet *cpkt);

int coap_packet_append_payload(struct coap_packet *cpkt, const uint8_t *payload,
                               uint16_t payload_len);

bool coap_packet_is_request(const struct coap_packet *cpkt);

int coap_handle_request_len(struct coap_packet *cpkt,
                            struct coap_resource *resources,
                            size_t resources_len,
                            struct coap_option *options,
                            uint8_t opt_num,
                            struct net_sockaddr *addr, net_socklen_t addr_len);

int coap_handle_request(struct coap_packet *cpkt,
                        struct coap_resource *resources,
                        struct coap_option *options,
                        uint8_t opt_num,
                        struct net_sockaddr *addr, net_socklen_t addr_len);

enum coap_block_size {
        COAP_BLOCK_16,   
        COAP_BLOCK_32,   
        COAP_BLOCK_64,   
        COAP_BLOCK_128,  
        COAP_BLOCK_256,  
        COAP_BLOCK_512,  
        COAP_BLOCK_1024, 
        COAP_BLOCK_BERT, 
};

static inline uint16_t coap_block_size_to_bytes(
        enum coap_block_size block_size)
{
        /* BERT (SZX=7) acts like 1024 bytes for size calculations per RFC 8323 */
        if (block_size == COAP_BLOCK_BERT) {
                return 1024;
        }
 
        return (1 << (block_size + 4));
}

static inline enum coap_block_size coap_bytes_to_block_size(uint16_t bytes)
{
        int sz = u32_count_trailing_zeros(bytes) - 4;
 
        if (sz < COAP_BLOCK_16) {
                return COAP_BLOCK_16;
        }
        if (sz > COAP_BLOCK_1024) {
#if defined(CONFIG_COAP_OVER_RELIABLE_TRANSPORT)
                return COAP_BLOCK_BERT;
#else
                return COAP_BLOCK_1024;
#endif /* defined(CONFIG_COAP_OVER_RELIABLE_TRANSPORT) */
        }
        return (enum coap_block_size)sz;
}

struct coap_block_context {
        size_t total_size;
        size_t current;
        enum coap_block_size block_size;
};

int coap_block_transfer_init(struct coap_block_context *ctx,
                             enum coap_block_size block_size,
                             size_t total_size);

int coap_append_descriptive_block_option(struct coap_packet *cpkt, struct coap_block_context *ctx);

bool coap_has_descriptive_block_option(struct coap_packet *cpkt);

int coap_remove_descriptive_block_option(struct coap_packet *cpkt);

bool coap_block_has_more(struct coap_packet *cpkt);

int coap_append_block1_option(struct coap_packet *cpkt,
                              struct coap_block_context *ctx);

int coap_append_block2_option(struct coap_packet *cpkt,
                              struct coap_block_context *ctx);

int coap_append_size1_option(struct coap_packet *cpkt,
                             struct coap_block_context *ctx);

int coap_append_size2_option(struct coap_packet *cpkt,
                             struct coap_block_context *ctx);

int coap_get_option_int(const struct coap_packet *cpkt, uint16_t code);

int coap_get_block1_option(const struct coap_packet *cpkt, bool *has_more, uint32_t *block_number);

int coap_get_block2_option(const struct coap_packet *cpkt, bool *has_more,
                           uint32_t *block_number);

int coap_update_from_block(const struct coap_packet *cpkt,
                           struct coap_block_context *ctx);

int coap_next_block_for_option(const struct coap_packet *cpkt,
                               struct coap_block_context *ctx,
                               enum coap_option_num option);

size_t coap_next_block(const struct coap_packet *cpkt,
                       struct coap_block_context *ctx);

void coap_observer_init(struct coap_observer *observer,
                        const struct coap_packet *request,
                        const struct net_sockaddr *addr);
 
#if defined(CONFIG_COAP_OSCORE) || defined(__DOXYGEN__)
void coap_observer_init_oscore(struct coap_observer *observer, const struct coap_packet *request,
                               const struct net_sockaddr *addr,
                               struct coap_oscore_context *oscore_ctx);
#endif /* CONFIG_COAP_OSCORE */

bool coap_register_observer(struct coap_resource *resource,
                            struct coap_observer *observer);

bool coap_remove_observer(struct coap_resource *resource,
                          struct coap_observer *observer);

struct coap_observer *coap_find_observer(
        struct coap_observer *observers, size_t len,
        const struct net_sockaddr *addr,
        const uint8_t *token, uint8_t token_len);

struct coap_observer *coap_find_observer_by_addr(
        struct coap_observer *observers, size_t len,
        const struct net_sockaddr *addr);

struct coap_observer *coap_find_observer_by_token(
        struct coap_observer *observers, size_t len,
        const uint8_t *token, uint8_t token_len);

struct coap_observer *coap_observer_next_unused(
        struct coap_observer *observers, size_t len);

void coap_reply_init(struct coap_reply *reply,
                     const struct coap_packet *request);

int coap_pending_init(struct coap_pending *pending,
                      const struct coap_packet *request,
                      const struct net_sockaddr *addr,
                      const struct coap_transmission_parameters *params);

struct coap_pending *coap_pending_next_unused(
        struct coap_pending *pendings, size_t len);

struct coap_reply *coap_reply_next_unused(
        struct coap_reply *replies, size_t len);

struct coap_pending *coap_pending_received(
        const struct coap_packet *response,
        struct coap_pending *pendings, size_t len);

struct coap_reply *coap_response_received(
        const struct coap_packet *response,
        const struct net_sockaddr *from,
        struct coap_reply *replies, size_t len);

struct coap_pending *coap_pending_next_to_expire(
        struct coap_pending *pendings, size_t len);

bool coap_pending_cycle(struct coap_pending *pending);

void coap_pending_clear(struct coap_pending *pending);

void coap_pendings_clear(struct coap_pending *pendings, size_t len);

size_t coap_pendings_count(struct coap_pending *pendings, size_t len);

void coap_reply_clear(struct coap_reply *reply);

void coap_replies_clear(struct coap_reply *replies, size_t len);

int coap_resource_notify(struct coap_resource *resource);

bool coap_request_is_observe(const struct coap_packet *request);

struct coap_transmission_parameters coap_get_transmission_parameters(void);

void coap_set_transmission_parameters(const struct coap_transmission_parameters *params);

int coap_check_unsupported_critical_options(const struct coap_packet *cpkt, uint16_t *opt);

uint8_t coap_tcp_header_get_token(const struct coap_packet *cpkt,
                                  uint8_t *token);

uint8_t coap_tcp_header_get_code(const struct coap_packet *cpkt);

const uint8_t *coap_tcp_packet_get_payload(const struct coap_packet *cpkt,
                                           uint32_t *len);

int coap_tcp_packet_parse(struct coap_packet *cpkt, uint8_t *data, uint16_t len,
                          struct coap_option *options, uint8_t opt_num);

int coap_tcp_packet_init(struct coap_packet *cpkt, uint8_t *data,
                         uint16_t max_len, uint8_t token_len,
                         const uint8_t *token, uint8_t code);

int coap_tcp_packet_update_len(struct coap_packet *cpkt);

int coap_tcp_append_block2_option(struct coap_packet *cpkt,
                                  struct coap_block_context *ctx);

int coap_tcp_update_from_block(const struct coap_packet *cpkt,
                               struct coap_block_context *ctx);

size_t coap_tcp_next_block(const struct coap_packet *cpkt,
                           struct coap_block_context *ctx);
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_NET_COAP_H_ */