1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 3 /* 4 * coap_oscore_internal.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_internal.h 18 * @brief CoAP OSCORE internal information 19 */ 20 21 #ifndef COAP_OSCORE_INTERNAL_H_ 22 #define COAP_OSCORE_INTERNAL_H_ 23 24 #include "oscore/oscore_context.h" 25 26 /** 27 * @ingroup internal_api 28 * @defgroup oscore_internal OSCORE Support 29 * Internal API for interfacing with OSCORE (RFC8613) 30 * @{ 31 */ 32 33 /** 34 * The structure used to hold the OSCORE configuration information 35 */ 36 struct coap_oscore_conf_t { 37 coap_bin_const_t *master_secret; /**< Common Master Secret */ 38 coap_bin_const_t *master_salt; /**< Common Master Salt */ 39 coap_bin_const_t *sender_id; /**< Sender ID (i.e. local our id) */ 40 coap_bin_const_t *id_context; /**< Common ID context */ 41 coap_bin_const_t **recipient_id; /**< Recipient ID (i.e. remote peer id) 42 Array of recipient_id */ 43 uint32_t recipient_id_count; /**< Number of recipient_id entries */ 44 uint32_t replay_window; /**< Replay window size 45 Use COAP_OSCORE_DEFAULT_REPLAY_WINDOW */ 46 uint32_t ssn_freq; /**< Sender Seq Num update frequency */ 47 cose_alg_t aead_alg; /**< Set to one of COSE_ALGORITHM_AES* */ 48 cose_hkdf_alg_t hkdf_alg; /**< Set to one of COSE_HKDF_ALG_* */ 49 uint32_t rfc8613_b_1_2; /**< 1 if rfc8613 B.1.2 enabled else 0 */ 50 uint32_t rfc8613_b_2; /**< 1 if rfc8613 B.2 protocol else 0 */ 51 52 /* General Testing */ 53 uint32_t break_sender_key; /**< 1 if sender key to be broken, else 0 */ 54 uint32_t break_recipient_key; /**< 1 if recipient key to be broken, else 0 */ 55 56 /* SSN handling (not in oscore_config[]) */ 57 coap_oscore_save_seq_num_t save_seq_num_func; /**< Called every seq num 58 change */ 59 void *save_seq_num_func_param; /**< Passed to save_seq_num_func() */ 60 uint64_t start_seq_num; /**< Used for ssn_freq updating */ 61 }; 62 63 typedef enum oscore_partial_iv_t { 64 OSCORE_SEND_NO_IV, /**< Do not send partial IV unless added by a response */ 65 OSCORE_SEND_PARTIAL_IV /**< Send partial IV with encrypted PDU */ 66 } oscore_partial_iv_t; 67 68 /** 69 * Encrypts the specified @p pdu when OSCORE encryption is required 70 * on @p session. This function returns the encrypted PDU or @c NULL 71 * on error. 72 * 73 * @param session The session that will handle the transport of the 74 * specified @p pdu. 75 * @param pdu The PDU to encrypt if necessary. 76 * @param kid_context Optional kid context to use or NULL. 77 * @param send_partial_iv @c OSCORE_SEND_PARTIAL_IV if partial_iv is always to 78 * be added, else @c OSCORE_SEND_NO_IV if not to be 79 * added for a response if not required. 80 * 81 * @return The OSCORE encrypted version of @p pdu, or @c NULL on error. 82 */ 83 coap_pdu_t *coap_oscore_new_pdu_encrypted(coap_session_t *session, 84 coap_pdu_t *pdu, 85 coap_bin_const_t *kid_context, 86 oscore_partial_iv_t send_partial_iv); 87 88 /** 89 * Decrypts the OSCORE-encrypted parts of @p pdu when OSCORE is used. 90 * This function returns the decrypted PDU or @c NULL on error. 91 * 92 * @param session The session that will handle the transport of the 93 * specified @p pdu. 94 * @param pdu The PDU to decrypt if necessary. 95 * 96 * @return The decrypted @p pdu, or @c NULL on error. 97 */ 98 struct coap_pdu_t *coap_oscore_decrypt_pdu(coap_session_t *session, 99 coap_pdu_t *pdu); 100 101 /** 102 * Cleanup all allocated OSCORE information. 103 * 104 * @param context The context that the OSCORE information is associated with. 105 */ 106 void coap_delete_all_oscore(coap_context_t *context); 107 108 /** 109 * Cleanup all allocated OSCORE association information. 110 * 111 * @param session The session that the OSCORE associations are associated with. 112 */ 113 void coap_delete_oscore_associations(coap_session_t *session); 114 115 /** 116 * Determine the additional data size requirements for adding in OSCORE. 117 * 118 * @param session The session that the OSCORE associations are associated with. 119 * @param pdu The non OSCORE protected PDU that is going to be used. 120 * 121 * @return The OSCORE packet size overhead. 122 */ 123 size_t coap_oscore_overhead(coap_session_t *session, coap_pdu_t *pdu); 124 125 /** 126 * Convert PDU to use Proxy-Scheme option if Proxy-Uri option is present 127 * 128 * @param pdu The PDU to check and update if appropriate. 129 * 130 * @return @c 1 success, else @c 0 failure. 131 */ 132 int coap_rebuild_pdu_for_proxy(coap_pdu_t *pdu); 133 134 /** 135 * Initiate an OSCORE session 136 * 137 * @param session The session that the OSCORE associations are associated with. 138 * @param oscore_conf The OSCORE configuration. 139 * 140 * @return @c 1 success, else @c 0 failure. 141 */ 142 int coap_oscore_initiate(coap_session_t *session, 143 coap_oscore_conf_t *oscore_conf); 144 145 /** @} */ 146 147 #endif /* COAP_OSCORE_INTERNAL_H */ 148