1 /* Copyright (C) 2020 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz> 2 3 This program is free software: you can redistribute it and/or modify 4 it under the terms of the GNU General Public License as published by 5 the Free Software Foundation, either version 3 of the License, or 6 (at your option) any later version. 7 8 This program is distributed in the hope that it will be useful, 9 but WITHOUT ANY WARRANTY; without even the implied warranty of 10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License 14 along with this program. If not, see <https://www.gnu.org/licenses/>. 15 */ 16 17 /*! 18 * \file 19 * 20 * \addtogroup tsig 21 * 22 * \brief Low-level TSIG signing API. 23 * 24 * @{ 25 */ 26 27 #pragma once 28 29 #include <stdint.h> 30 31 #include <libdnssec/binary.h> 32 33 /*! 34 * TSIG algorithms. 35 * 36 * \note The numeric values are library specific. 37 */ 38 typedef enum dnssec_tsig_algorithm { 39 DNSSEC_TSIG_UNKNOWN = 0, 40 DNSSEC_TSIG_HMAC_MD5, 41 DNSSEC_TSIG_HMAC_SHA1, 42 DNSSEC_TSIG_HMAC_SHA224, 43 DNSSEC_TSIG_HMAC_SHA256, 44 DNSSEC_TSIG_HMAC_SHA384, 45 DNSSEC_TSIG_HMAC_SHA512 46 } dnssec_tsig_algorithm_t; 47 48 /*! 49 * Get TSIG algorithm number from domain name. 50 * 51 * \see https://www.iana.org/assignments/tsig-algorithm-names/tsig-algorithm-names.xhtml 52 * 53 * \param dname Domain name of the algorithm (e.g., 0x0b hmac-sha256). 54 * 55 * \return TSIG algorithm. 56 */ 57 dnssec_tsig_algorithm_t dnssec_tsig_algorithm_from_dname(const uint8_t *dname); 58 59 /*! 60 * Get a domain name of the TSIG algorithm. 61 * 62 * \param algorithm TSIG algorithm. 63 * 64 * \return Domain name of the TSIG algorithm. 65 */ 66 const uint8_t *dnssec_tsig_algorithm_to_dname(dnssec_tsig_algorithm_t algorithm); 67 68 /*! 69 * Get TSIG algorithm from a MAC name. 70 * 71 * \param name MAC name (e.g., hmac-sha256). 72 * 73 * \return TSIG algorithm. 74 */ 75 dnssec_tsig_algorithm_t dnssec_tsig_algorithm_from_name(const char *name); 76 77 /*! 78 * Get MAC name from a TSIG algorithm. 79 * 80 * \param algorithm TSIG algorithm. 81 * 82 * \return MAC name of the TSIG algorithm. 83 */ 84 const char *dnssec_tsig_algorithm_to_name(dnssec_tsig_algorithm_t algorithm); 85 86 /*! 87 * Get optimal size of a TSIG algorithm. 88 */ 89 int dnssec_tsig_optimal_key_size(dnssec_tsig_algorithm_t algorithm); 90 91 struct dnssec_tsig_ctx; 92 93 /*! 94 * TSIG signing context. 95 */ 96 typedef struct dnssec_tsig_ctx dnssec_tsig_ctx_t; 97 98 /*! 99 * Create new TSIG signing context. 100 * 101 * \param[out] ctx Resulting TSIG context. 102 * \param[in] algorithm TSIG algorithm. 103 * \param[in] key Shared key to be used for signing. 104 * 105 * \return Error code, DNSSEC_EOK if successful. 106 */ 107 int dnssec_tsig_new(dnssec_tsig_ctx_t **ctx, dnssec_tsig_algorithm_t algorithm, 108 const dnssec_binary_t *key); 109 110 /*! 111 * Free the TSIG signing context. 112 * 113 * \param ctx TSIG signing context to be freed. 114 */ 115 void dnssec_tsig_free(dnssec_tsig_ctx_t *ctx); 116 117 /*! 118 * Add data to be signed by TSIG. 119 * 120 * \param ctx TSIG signing context. 121 * \param data Data to be signed. 122 * 123 * \return Error code, DNSSEC_EOK if successful. 124 */ 125 int dnssec_tsig_add(dnssec_tsig_ctx_t *ctx, const dnssec_binary_t *data); 126 127 /*! 128 * Get size of the TSIG signature for given signing context. 129 * 130 * \param ctx TSIG signing context. 131 * 132 * \return The size of the TSIG signature. 133 */ 134 size_t dnssec_tsig_size(dnssec_tsig_ctx_t *ctx); 135 136 /*! 137 * Get size of the TSIG signature for given algorithm. 138 * 139 * \param algorithm TSIG algorithm. 140 * 141 * \return The size of the TSIG signature. 142 */ 143 size_t dnssec_tsig_algorithm_size(dnssec_tsig_algorithm_t algorithm); 144 145 /*! 146 * Write TSIG signature. 147 * 148 * \param[in] ctx TSIG signing context. 149 * \param[out] mac Resulting TSIG signature. 150 * 151 * \return Error code, DNSSEC_EOK if successful. 152 */ 153 int dnssec_tsig_write(dnssec_tsig_ctx_t *ctx, uint8_t *mac); 154 155 /*! @} */ 156