1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 3 /* 4 * coap_oscore.h -- Object Security for Constrained RESTful Environments 5 * (OSCORE) support for libcoap 6 * 7 * Copyright (C) 2019-2023 Olaf Bergmann <bergmann@tzi.org> 8 * Copyright (C) 2021-2023 Jon Shallow <supjps-libcoap@jpshallow.com> 9 * 10 * SPDX-License-Identifier: BSD-2-Clause 11 * 12 * This file is part of the CoAP library libcoap. Please see README for terms 13 * of use. 14 */ 15 16 /** 17 * @file coap_oscore.h 18 * @brief CoAP OSCORE support 19 */ 20 21 #ifndef COAP_OSCORE_H_ 22 #define COAP_OSCORE_H_ 23 24 /** 25 * @ingroup application_api 26 * @defgroup oscore OSCORE Support 27 * API functions for interfacing with OSCORE (RFC8613) 28 * @{ 29 */ 30 31 /** 32 * Check whether OSCORE is available. 33 * 34 * @return @c 1 if support for OSCORE is enabled, or @c 0 otherwise. 35 */ 36 int coap_oscore_is_supported(void); 37 38 /** 39 * Creates a new client session to the designated server, protecting the data 40 * using OSCORE. 41 * 42 * @param ctx The CoAP context. 43 * @param local_if Address of local interface. It is recommended to use NULL 44 * to let the operating system choose a suitable local 45 * interface. If an address is specified, the port number 46 * should be zero, which means that a free port is 47 * automatically selected. 48 * @param server The server's address. If the port number is zero, the default 49 * port for the protocol will be used. 50 * @param proto CoAP Protocol. 51 * @param oscore_conf OSCORE configuration information. This structure is 52 * freed off by this call. 53 * 54 * @return A new CoAP session or NULL if failed. Call coap_session_release() 55 * to free. 56 */ 57 coap_session_t *coap_new_client_session_oscore(coap_context_t *ctx, 58 const coap_address_t *local_if, 59 const coap_address_t *server, 60 coap_proto_t proto, 61 coap_oscore_conf_t *oscore_conf); 62 63 /** 64 * Creates a new client session to the designated server with PSK credentials 65 * as well as protecting the data using OSCORE. 66 * 67 * @param ctx The CoAP context. 68 * @param local_if Address of local interface. It is recommended to use NULL to 69 * let the operating system choose a suitable local interface. 70 * If an address is specified, the port number should be zero, 71 * which means that a free port is automatically selected. 72 * @param server The server's address. If the port number is zero, the default 73 * port for the protocol will be used. 74 * @param proto CoAP Protocol. 75 * @param psk_data PSK parameters. 76 * @param oscore_conf OSCORE configuration information. This structure is 77 * freed off by this call. 78 * 79 * @return A new CoAP session or NULL if failed. Call coap_session_release() 80 * to free. 81 */ 82 coap_session_t *coap_new_client_session_oscore_psk(coap_context_t *ctx, 83 const coap_address_t *local_if, 84 const coap_address_t *server, 85 coap_proto_t proto, 86 coap_dtls_cpsk_t *psk_data, 87 coap_oscore_conf_t *oscore_conf); 88 89 /** 90 * Creates a new client session to the designated server with PKI credentials 91 * as well as protecting the data using OSCORE. 92 * 93 * @param ctx The CoAP context. 94 * @param local_if Address of local interface. It is recommended to use NULL to 95 * let the operating system choose a suitable local interface. 96 * If an address is specified, the port number should be zero, 97 * which means that a free port is automatically selected. 98 * @param server The server's address. If the port number is zero, the default 99 * port for the protocol will be used. 100 * @param proto CoAP Protocol. 101 * @param pki_data PKI parameters. 102 * @param oscore_conf OSCORE configuration information. This structure is 103 * freed off by this call. 104 * 105 * @return A new CoAP session or NULL if failed. Call coap_session_release() 106 * to free. 107 */ 108 coap_session_t *coap_new_client_session_oscore_pki(coap_context_t *ctx, 109 const coap_address_t *local_if, 110 const coap_address_t *server, 111 coap_proto_t proto, 112 coap_dtls_pki_t *pki_data, 113 coap_oscore_conf_t *oscore_conf); 114 115 /** 116 * Set the context's default OSCORE configuration for a server. 117 * 118 * @param context The current coap_context_t object. 119 * @param oscore_conf OSCORE configuration information. This structure is 120 * freed off by this call. 121 * 122 * @return @c 1 if successful, else @c 0. 123 */ 124 int coap_context_oscore_server(coap_context_t *context, 125 coap_oscore_conf_t *oscore_conf); 126 127 /** 128 * Definition of the function used to save the current Sender Sequence Number 129 * 130 * @param sender_seq_num The Sender Sequence Number to save in non-volatile 131 * memory. 132 * @param param The save_seq_num_func_param provided to 133 * coap_new_oscore_context(). 134 * 135 * @return @c 1 if success, else @c 0 if a failure of some sort. 136 */ 137 typedef int (*coap_oscore_save_seq_num_t)(uint64_t sender_seq_num, void *param); 138 139 /** 140 * Parse an OSCORE configuration (held in memory) and populate a OSCORE 141 * configuration structure. 142 * 143 * @param conf_mem The current configuration in memory. 144 * @param save_seq_num_func Function to call to save Sender Sequence Number in 145 * non-volatile memory, or NULL. 146 * @param save_seq_num_func_param Parameter to pass into 147 * save_seq_num_func() function. 148 * @param start_seq_num The Sender Sequence Number to start with following a 149 * reboot retrieved out of non-volatile menory or 0. 150 * 151 * @return The new OSCORE configuration. NULL if failed. It needs to be freed 152 * off with coap_delete_oscore_conf() when no longer required, 153 * otherwise it is freed off when coap_free_context() is called. 154 */ 155 coap_oscore_conf_t *coap_new_oscore_conf(coap_str_const_t conf_mem, 156 coap_oscore_save_seq_num_t save_seq_num_func, 157 void *save_seq_num_func_param, 158 uint64_t start_seq_num); 159 160 /** 161 * Release all the information associated with the OSCORE configuration. 162 * 163 * @param oscore_conf The OSCORE configuration structure to release. 164 * 165 * @return @c 1 Successfully removed, else @c 0 not found. 166 */ 167 int coap_delete_oscore_conf(coap_oscore_conf_t *oscore_conf); 168 169 /** 170 * Add in the specific Recipient ID into the OSCORE context (server only). 171 * Note: This is only added to the OSCORE context as first defined by 172 * coap_new_client_session_oscore*() or coap_context_oscore_server(). 173 * 174 * @param context The CoAP context to add the OSCORE recipient_id to. 175 * @param recipient_id The Recipient ID to add. 176 * 177 * @return @c 1 Successfully added, else @c 0 there is an issue. 178 */ 179 int coap_new_oscore_recipient(coap_context_t *context, 180 coap_bin_const_t *recipient_id); 181 182 /** 183 * Release all the information associated for the specific Recipient ID 184 * (and hence and stop any further OSCORE protection for this Recipient). 185 * Note: This is only removed from the OSCORE context as first defined by 186 * coap_new_client_session_oscore*() or coap_context_oscore_server(). 187 * 188 * @param context The CoAP context holding the OSCORE recipient_id to. 189 * @param recipient_id The Recipient ID to remove. 190 * 191 * @return @c 1 Successfully removed, else @c 0 not found. 192 */ 193 int coap_delete_oscore_recipient(coap_context_t *context, 194 coap_bin_const_t *recipient_id); 195 196 /** @} */ 197 198 #endif /* COAP_OSCORE_H */ 199