1 /* 2 * coap_dtls_internal.h -- (Datagram) Transport Layer Support for libcoap 3 * 4 * Copyright (C) 2016 Olaf Bergmann <bergmann@tzi.org> 5 * Copyright (C) 2017 Jean-Claude Michelou <jcm@spinetix.com> 6 * 7 * SPDX-License-Identifier: BSD-2-Clause 8 * 9 * This file is part of the CoAP library libcoap. Please see README for terms 10 * of use. 11 */ 12 13 #ifndef COAP_DTLS_INTERNAL_H_ 14 #define COAP_DTLS_INTERNAL_H_ 15 16 /** 17 * @defgroup dtls_internal DTLS Support (Internal) 18 * CoAP DTLS Structures, Enums and Functions that are not exposed to 19 * applications 20 * @{ 21 */ 22 23 /* https://tools.ietf.org/html/rfc6347#section-4.2.4.1 */ 24 #ifndef COAP_DTLS_RETRANSMIT_MS 25 #define COAP_DTLS_RETRANSMIT_MS 1000 26 #endif 27 #ifndef COAP_DTLS_RETRANSMIT_TOTAL_MS 28 #define COAP_DTLS_RETRANSMIT_TOTAL_MS 60000 29 #endif 30 31 #define COAP_DTLS_RETRANSMIT_COAP_TICKS (COAP_DTLS_RETRANSMIT_MS * COAP_TICKS_PER_SECOND / 1000) 32 33 /** 34 * Creates a new DTLS context for the given @p coap_context. This function 35 * returns a pointer to a new DTLS context object or @c NULL on error. 36 * 37 * @param coap_context The CoAP context where the DTLS object shall be used. 38 * 39 * @return A DTLS context object or @c NULL on error. 40 */ 41 void * 42 coap_dtls_new_context(coap_context_t *coap_context); 43 44 /** 45 * Set the DTLS context's default server PSK information. 46 * This does the PSK specifics following coap_dtls_new_context(). 47 * 48 * @param coap_context The CoAP context. 49 * @param setup_data A structure containing setup data originally passed into 50 * coap_context_set_psk2(). 51 * 52 * @return @c 1 if successful, else @c 0. 53 */ 54 55 int 56 coap_dtls_context_set_spsk(coap_context_t *coap_context, 57 coap_dtls_spsk_t *setup_data); 58 59 /** 60 * Set the DTLS context's default client PSK information. 61 * This does the PSK specifics following coap_dtls_new_context(). 62 * 63 * @param coap_context The CoAP context. 64 * @param setup_data A structure containing setup data originally passed into 65 * coap_new_client_session_psk2(). 66 * 67 * @return @c 1 if successful, else @c 0. 68 */ 69 70 int 71 coap_dtls_context_set_cpsk(coap_context_t *coap_context, 72 coap_dtls_cpsk_t *setup_data); 73 74 /** 75 * Set the DTLS context's default server PKI information. 76 * This does the PKI specifics following coap_dtls_new_context(). 77 * If @p COAP_DTLS_ROLE_SERVER, then the information will get put into the 78 * TLS library's context (from which sessions are derived). 79 * If @p COAP_DTLS_ROLE_CLIENT, then the information will get put into the 80 * TLS library's session. 81 * 82 * @param coap_context The CoAP context. 83 * @param setup_data Setup information defining how PKI is to be setup. 84 * Required parameter. If @p NULL, PKI will not be 85 * set up. 86 * @param role One of @p COAP_DTLS_ROLE_CLIENT or @p COAP_DTLS_ROLE_SERVER 87 * 88 * @return @c 1 if successful, else @c 0. 89 */ 90 91 int 92 coap_dtls_context_set_pki(coap_context_t *coap_context, 93 const coap_dtls_pki_t *setup_data, 94 const coap_dtls_role_t role); 95 96 /** 97 * Set the dtls context's default Root CA information for a client or server. 98 * 99 * @param coap_context The current coap_context_t object. 100 * @param ca_file If not @p NULL, is the full path name of a PEM encoded 101 * file containing all the Root CAs to be used. 102 * @param ca_dir If not @p NULL, points to a directory containing PEM 103 * encoded files containing all the Root CAs to be used. 104 * 105 * @return @c 1 if successful, else @c 0. 106 */ 107 108 int 109 coap_dtls_context_set_pki_root_cas(coap_context_t *coap_context, 110 const char *ca_file, 111 const char *ca_dir); 112 113 /** 114 * Check whether one of the coap_dtls_context_set_{psk|pki}() functions have 115 * been called. 116 * 117 * @param coap_context The current coap_context_t object. 118 * 119 * @return @c 1 if coap_dtls_context_set_{psk|pki}() called, else @c 0. 120 */ 121 122 int coap_dtls_context_check_keys_enabled(coap_context_t *coap_context); 123 124 /** 125 * Releases the storage allocated for @p dtls_context. 126 * 127 * @param dtls_context The DTLS context as returned by coap_dtls_new_context(). 128 */ 129 void coap_dtls_free_context(void *dtls_context); 130 131 /** 132 * Create a new client-side session. This should send a HELLO to the server. 133 * 134 * @param coap_session The CoAP session. 135 * 136 * @return Opaque handle to underlying TLS library object containing security 137 * parameters for the session. 138 */ 139 void *coap_dtls_new_client_session(coap_session_t *coap_session); 140 141 /** 142 * Create a new DTLS server-side session. 143 * Called after coap_dtls_hello() has returned @c 1, signalling that a validated 144 * HELLO was received from a client. 145 * This should send a HELLO to the server. 146 * 147 * @param coap_session The CoAP session. 148 * 149 * @return Opaque handle to underlying TLS library object containing security 150 * parameters for the DTLS session. 151 */ 152 void *coap_dtls_new_server_session(coap_session_t *coap_session); 153 154 /** 155 * Terminates the DTLS session (may send an ALERT if necessary) then frees the 156 * underlying TLS library object containing security parameters for the session. 157 * 158 * @param coap_session The CoAP session. 159 */ 160 void coap_dtls_free_session(coap_session_t *coap_session); 161 162 /** 163 * Notify of a change in the CoAP session's MTU, for example after 164 * a PMTU update. 165 * 166 * @param coap_session The CoAP session. 167 */ 168 void coap_dtls_session_update_mtu(coap_session_t *coap_session); 169 170 /** 171 * Send data to a DTLS peer. 172 * 173 * @param coap_session The CoAP session. 174 * @param data pointer to data. 175 * @param data_len Number of bytes to send. 176 * 177 * @return @c 0 if this would be blocking, @c -1 if there is an error or the 178 * number of cleartext bytes sent. 179 */ 180 int coap_dtls_send(coap_session_t *coap_session, 181 const uint8_t *data, 182 size_t data_len); 183 184 /** 185 * Check if timeout is handled per CoAP session or per CoAP context. 186 * 187 * @return @c 1 of timeout and retransmit is per context, @c 0 if it is 188 * per session. 189 */ 190 int coap_dtls_is_context_timeout(void); 191 192 /** 193 * Do all pending retransmits and get next timeout 194 * 195 * @param dtls_context The DTLS context. 196 * 197 * @return @c 0 if no event is pending or date of the next retransmit. 198 */ 199 coap_tick_t coap_dtls_get_context_timeout(void *dtls_context); 200 201 /** 202 * Get next timeout for this session. 203 * 204 * @param coap_session The CoAP session. 205 * @param now The current time in ticks. 206 * 207 * @return @c 0 If no event is pending or ticks time of the next retransmit. 208 */ 209 coap_tick_t coap_dtls_get_timeout(coap_session_t *coap_session, 210 coap_tick_t now); 211 212 /** 213 * Handle a DTLS timeout expiration. 214 * 215 * @param coap_session The CoAP session. 216 */ 217 void coap_dtls_handle_timeout(coap_session_t *coap_session); 218 219 /** 220 * Handling incoming data from a DTLS peer. 221 * 222 * @param coap_session The CoAP session. 223 * @param data Encrypted datagram. 224 * @param data_len Encrypted datagram size. 225 * 226 * @return Result of coap_handle_dgram on the decrypted CoAP PDU 227 * or @c -1 for error. 228 */ 229 int coap_dtls_receive(coap_session_t *coap_session, 230 const uint8_t *data, 231 size_t data_len); 232 233 /** 234 * Handling client HELLO messages from a new candiate peer. 235 * Note that session->tls is empty. 236 * 237 * @param coap_session The CoAP session. 238 * @param data Encrypted datagram. 239 * @param data_len Encrypted datagram size. 240 * 241 * @return @c 0 if a cookie verification message has been sent, @c 1 if the 242 * HELLO contains a valid cookie and a server session should be created, 243 * @c -1 if the message is invalid. 244 */ 245 int coap_dtls_hello(coap_session_t *coap_session, 246 const uint8_t *data, 247 size_t data_len); 248 249 /** 250 * Get DTLS overhead over cleartext PDUs. 251 * 252 * @param coap_session The CoAP session. 253 * 254 * @return Maximum number of bytes added by DTLS layer. 255 */ 256 unsigned int coap_dtls_get_overhead(coap_session_t *coap_session); 257 258 /** 259 * Create a new TLS client-side session. 260 * 261 * @param coap_session The CoAP session. 262 * @param connected Updated with whether the connection is connected yet or not. 263 * @c 0 is not connected, @c 1 is connected. 264 * 265 * @return Opaque handle to underlying TLS library object containing security 266 * parameters for the session. 267 */ 268 void *coap_tls_new_client_session(coap_session_t *coap_session, int *connected); 269 270 /** 271 * Create a TLS new server-side session. 272 * 273 * @param coap_session The CoAP session. 274 * @param connected Updated with whether the connection is connected yet or not. 275 * @c 0 is not connected, @c 1 is connected. 276 * 277 * @return Opaque handle to underlying TLS library object containing security 278 * parameters for the session. 279 */ 280 void *coap_tls_new_server_session(coap_session_t *coap_session, int *connected); 281 282 /** 283 * Terminates the TLS session (may send an ALERT if necessary) then frees the 284 * underlying TLS library object containing security parameters for the session. 285 * 286 * @param coap_session The CoAP session. 287 */ 288 void coap_tls_free_session( coap_session_t *coap_session ); 289 290 /** 291 * Send data to a TLS peer, with implicit flush. 292 * 293 * @param coap_session The CoAP session. 294 * @param data Pointer to data. 295 * @param data_len Number of bytes to send. 296 * 297 * @return @c 0 if this should be retried, @c -1 if there is an error 298 * or the number of cleartext bytes sent. 299 */ 300 ssize_t coap_tls_write(coap_session_t *coap_session, 301 const uint8_t *data, 302 size_t data_len 303 ); 304 305 /** 306 * Read some data from a TLS peer. 307 * 308 * @param coap_session The CoAP session. 309 * @param data Pointer to data. 310 * @param data_len Maximum number of bytes to read. 311 * 312 * @return @c 0 if this should be retried, @c -1 if there is an error 313 * or the number of cleartext bytes read. 314 */ 315 ssize_t coap_tls_read(coap_session_t *coap_session, 316 uint8_t *data, 317 size_t data_len 318 ); 319 320 /** 321 * Initialize the underlying (D)TLS Library layer. 322 * 323 */ 324 void coap_dtls_startup(void); 325 326 /** 327 * Close down the underlying (D)TLS Library layer. 328 * 329 */ 330 void coap_dtls_shutdown(void); 331 332 /** 333 * Get the actual (D)TLS object for the session. 334 * 335 * @param session The session. 336 * @param tls_lib Updated with the library type. 337 * 338 * @return The TLS information. 339 */ 340 void *coap_dtls_get_tls(const coap_session_t *session, 341 coap_tls_library_t *tls_lib); 342 343 /** @} */ 344 345 #endif /* COAP_DTLS_INTERNAL_H */ 346