1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 3 /* 4 * coap_crypto_internal.h -- Structures, Enums & Functions that are not 5 * exposed to application programming 6 * 7 * Copyright (C) 2017-2023 Olaf Bergmann <bergmann@tzi.org> 8 * Copyright (C) 2021-2023 Jon Shallow <supjps-ietf@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_crypto_internal.h 18 * @brief COAP crypto internal information 19 */ 20 21 #ifndef COAP_CRYPTO_INTERNAL_H_ 22 #define COAP_CRYPTO_INTERNAL_H_ 23 24 /** 25 * @ingroup internal_api 26 * @defgroup crypto_internal OSCORE Crypto Support 27 * Internal API for interfacing with Crypto libraries 28 * @{ 29 */ 30 31 #include "oscore/oscore_cose.h" 32 33 #ifndef COAP_CRYPTO_MAX_KEY_SIZE 34 #define COAP_CRYPTO_MAX_KEY_SIZE (32) 35 #endif /* COAP_CRYPTO_MAX_KEY_SIZE */ 36 37 #ifndef COAP_OSCORE_DEFAULT_REPLAY_WINDOW 38 #define COAP_OSCORE_DEFAULT_REPLAY_WINDOW 32 39 #endif /* COAP_OSCORE_DEFAULT_REPLAY_WINDOW */ 40 41 /** 42 * The structure that holds the Crypto Key. 43 */ 44 typedef coap_bin_const_t coap_crypto_key_t; 45 46 /** 47 * The structure that holds the AES Crypto information 48 */ 49 typedef struct coap_crypto_aes_ccm_t { 50 coap_crypto_key_t key; /**< The Key to use */ 51 const uint8_t *nonce; /**< must be exactly 15 - l bytes */ 52 size_t tag_len; /**< The size of the Tag */ 53 size_t l; /**< The number of bytes in the length field */ 54 } coap_crypto_aes_ccm_t; 55 56 /** 57 * The common structure that holds the Crypto information 58 */ 59 typedef struct coap_crypto_param_t { 60 cose_alg_t alg; /**< The COSE algorith to use */ 61 union { 62 coap_crypto_aes_ccm_t aes; /**< Used if AES type encryption */ 63 coap_crypto_key_t key; /**< The key to use */ 64 } params; 65 } coap_crypto_param_t; 66 67 /** 68 * Check whether the defined cipher algorithm is supported by the underlying 69 * crypto library. 70 * 71 * @param alg The COSE algorithm to check. 72 * 73 * @return @c 1 if there is support, else @c 0. 74 */ 75 int coap_crypto_check_cipher_alg(cose_alg_t alg); 76 77 /** 78 * Check whether the defined hkdf algorithm is supported by the underlying 79 * crypto library. 80 * 81 * @param hkdf_alg The COSE HKDF algorithm to check. 82 * 83 * @return @c 1 if there is support, else @c 0. 84 */ 85 int coap_crypto_check_hkdf_alg(cose_hkdf_alg_t hkdf_alg); 86 87 /** 88 * Encrypt the provided plaintext data 89 * 90 * @param params The Encrypt/Decrypt/Hash paramaters. 91 * @param data The data to encrypt. 92 * @param aad The additional AAD information. 93 * @param result Where to put the encrypted data. 94 * @param max_result_len The maximum size for @p result 95 * (updated with actual size). 96 * 97 * @return @c 1 if the data was successfully encrypted, else @c 0. 98 */ 99 int coap_crypto_aead_encrypt(const coap_crypto_param_t *params, 100 coap_bin_const_t *data, 101 coap_bin_const_t *aad, 102 uint8_t *result, 103 size_t *max_result_len); 104 105 /** 106 * Decrypt the provided encrypted data into plaintext. 107 * 108 * @param params The Encrypt/Decrypt/Hash paramaters. 109 * @param data The data to decrypt. 110 * @param aad The additional AAD information. 111 * @param result Where to put the decrypted data. 112 * @param max_result_len The maximum size for @p result 113 * (updated with actual size). 114 * 115 * @return @c 1 if the data was successfully decrypted, else @c 0. 116 */ 117 int coap_crypto_aead_decrypt(const coap_crypto_param_t *params, 118 coap_bin_const_t *data, 119 coap_bin_const_t *aad, 120 uint8_t *result, 121 size_t *max_result_len); 122 123 /** 124 * Create a HMAC hash of the provided data. 125 * 126 * @param hmac_alg The COSE HMAC algorithm to use. 127 * @param key The key to use for the hash. 128 * @param data The data to hash. 129 * @param hmac Where to put the created hmac result if successful. 130 * 131 * @return @c 1 if the hmac of the data was successful, else @c 0. 132 * It is the responsibility of the caller to release the 133 * created hmac. 134 */ 135 int coap_crypto_hmac(cose_hmac_alg_t hmac_alg, 136 coap_bin_const_t *key, 137 coap_bin_const_t *data, 138 coap_bin_const_t **hmac); 139 140 /** 141 * Create a hash of the provided data. 142 * 143 * @param alg The hash algorithm. 144 * @param data The data to hash. 145 * @param hash Where to put the hash result if successful. 146 * 147 * @return @c 1 if the data was successfully hashed, else @c 0. 148 * It is the responsibility of the caller to release the 149 * created hash. 150 */ 151 int coap_crypto_hash(cose_alg_t alg, 152 const coap_bin_const_t *data, 153 coap_bin_const_t **hash); 154 155 /** @} */ 156 157 #endif /* COAP_CRYPTO_INTERNAL_H_ */ 158