tsig-op.h 7.15 KB
Newer Older
1
/*  Copyright (C) 2017 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
2 3 4 5 6 7 8 9 10 11 12 13 14 15

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
16 17 18 19 20 21 22 23
/*!
 * \file
 *
 * \brief TSIG signing and validating.
 *
 * \addtogroup libknot
 * @{
 */
24

25
#pragma once
26 27 28

#include <stdint.h>

29
#include "libknot/rrtype/tsig.h"
30
#include "libknot/rrset.h"
31 32 33 34

/*!
 * \brief Generate TSIG signature of a message.
 *
35 36 37 38 39
 * This function generates TSIG digest of the given message prepended with the
 * given Request MAC (if any) and appended with TSIG Variables. It also appends
 * the resulting TSIG RR to the message wire format and accordingly adjusts
 * the message size.
 *
Lubos Slovak's avatar
Lubos Slovak committed
40
 * \note This function does not save the new digest to the 'digest' parameter
41
 *       unless everything went OK. This allows sending the same buffer to
Lubos Slovak's avatar
Lubos Slovak committed
42 43
 *       the 'request_mac' and 'digest' parameters.
 *
44 45
 * \param msg Message to be signed.
 * \param msg_len Size of the message in bytes.
46
 * \param msg_max_len Maximum size of the message in bytes.
47 48
 * \param request_mac Request MAC. (may be NULL).
 * \param request_mac_len Size of the request MAC in bytes.
Lubos Slovak's avatar
Lubos Slovak committed
49 50
 * \param digest Buffer to save the digest in.
 * \param digest_len In: size of the buffer. Out: real size of the digest saved.
51 52 53
 * \param key TSIG used for signing.
 * \param tsig_rcode RCODE of the TSIG.
 * \param request_time_signed Clients time signed.
54 55 56
 *
 * \retval KNOT_EOK if everything went OK.
 * \retval TODO
57
 *
58
 * \todo This function should return TSIG errors by their codes which are
59
 *       positive values - this will be recognized by the caller.
60
 */
61
int knot_tsig_sign(uint8_t *msg, size_t *msg_len, size_t msg_max_len,
62
                   const uint8_t *request_mac, size_t request_mac_len,
Lubos Slovak's avatar
Lubos Slovak committed
63
                   uint8_t *digest, size_t *digest_len,
64
                   const knot_tsig_key_t *key, uint16_t tsig_rcode,
65
                   uint64_t request_time_signed);
66 67 68 69

/*!
 * \brief Generate TSIG signature of a 2nd or later message in a TCP session.
 *
70 71 72 73 74
 * This function generates TSIG digest of the given message prepended with the
 * given Request MAC (if any) and appended with TSIG Variables. It also appends
 * the resulting TSIG RR to the message wire format and accordingly adjusts
 * the message size.
 *
Lubos Slovak's avatar
Lubos Slovak committed
75
 * \note This function does not save the new digest to the 'digest' parameter
76
 *       unless everything went OK. This allows sending the same buffer to
Lubos Slovak's avatar
Lubos Slovak committed
77 78
 *       the 'request_mac' and 'digest' parameters.
 *
79 80
 * \param msg Message to be signed.
 * \param msg_len Size of the message in bytes.
81
 * \param msg_max_len Maximum size of the message in bytes.
82 83
 * \param prev_digest Previous digest sent by the server in the session.
 * \param prev_digest_len Size of the previous digest in bytes.
Lubos Slovak's avatar
Lubos Slovak committed
84 85
 * \param digest Buffer to save the digest in.
 * \param digest_len In: size of the buffer. Out: real size of the digest saved.
86 87 88
 * \param key TSIG key for signing.
 * \param to_sign Data being signed.
 * \param to_sign_len Size of the data being signed.
89 90 91
 *
 * \retval KNOT_EOK if successful.
 * \retval TODO
92
 *
93
 * \todo This function should return TSIG errors by their codes which are
94
 *       positive values - this will be recognized by the caller.
95
 */
96
int knot_tsig_sign_next(uint8_t *msg, size_t *msg_len, size_t msg_max_len,
97
                        const uint8_t *prev_digest, size_t prev_digest_len,
Lubos Slovak's avatar
Lubos Slovak committed
98
                        uint8_t *digest, size_t *digest_len,
99
                        const knot_tsig_key_t *key, uint8_t *to_sign,
100
                        size_t to_sign_len);
101 102 103 104 105 106 107

/*!
 * \brief Checks incoming request.
 *
 * \param tsig_rr TSIG extracted from the packet.
 * \param wire Wire format of the packet (including the TSIG RR).
 * \param size Size of the wire format of packet in bytes.
108
 * \param tsig_key TSIG key.
109 110 111
 *
 * \retval KNOT_EOK If the signature is valid.
 * \retval TODO
112
 *
113
 * \todo This function should return TSIG errors by their codes which are
114
 *       positive values - this will be recognized by the caller.
115 116
 */
int knot_tsig_server_check(const knot_rrset_t *tsig_rr,
117
                           const uint8_t *wire, size_t size,
118
                           const knot_tsig_key_t *tsig_key);
119 120 121 122 123 124 125 126 127

/*!
 * \brief Checks incoming response.
 *
 * \param tsig_rr TSIG extracted from the packet.
 * \param wire Wire format of the packet (including the TSIG RR).
 * \param size Size of the wire format of packet in bytes.
 * \param request_mac Request MAC. (may be NULL).
 * \param request_mac_len Size of the request MAC in bytes.
128 129
 * \param key TSIG key.
 * \param prev_time_signed Time for TSIG period validity.
130 131 132
 *
 * \retval KNOT_EOK If the signature is valid.
 * \retval TODO
133
 *
134
 * \todo This function should return TSIG errors by their codes which are
135
 *       positive values - this will be recognized by the caller.
136 137 138
 */
int knot_tsig_client_check(const knot_rrset_t *tsig_rr,
                           const uint8_t *wire, size_t size,
Jan Kadlec's avatar
Jan Kadlec committed
139
                           const uint8_t *request_mac, size_t request_mac_len,
140
                           const knot_tsig_key_t *key,
141
                           uint64_t prev_time_signed);
142 143 144 145 146 147 148 149 150

/*!
 * \brief Checks signature of 2nd or next packet in a TCP session.
 *
 * \param tsig_rr TSIG extracted from the packet.
 * \param wire Wire format of the packet (including the TSIG RR).
 * \param size Size of the wire format of packet in bytes.
 * \param prev_digest Previous digest sent by the server in the session.
 * \param prev_digest_len Size of the previous digest in bytes.
151 152
 * \param key TSIG key.
 * \param prev_time_signed Time for TSIG period validity.
153 154 155
 *
 * \retval KNOT_EOK If the signature is valid.
 * \retval TODO
156
 *
157
 * \todo This function should return TSIG errors by their codes which are
158
 *       positive values - this will be recognized by the caller.
159 160 161
 */
int knot_tsig_client_check_next(const knot_rrset_t *tsig_rr,
                                const uint8_t *wire, size_t size,
162
                                const uint8_t *prev_digest,
Jan Kadlec's avatar
Jan Kadlec committed
163
                                size_t prev_digest_len,
164
                                const knot_tsig_key_t *key,
165
                                uint64_t prev_time_signed);
166

167 168 169
/*!
 * \todo Documentation!
 */
170
int knot_tsig_add(uint8_t *msg, size_t *msg_len, size_t msg_max_len,
171
                  uint16_t tsig_rcode, const knot_rrset_t *tsig_rr);
172

173 174 175
/*! \brief Append TSIG RR to message.
 *  \todo Proper documentation.
 */
176 177 178
int knot_tsig_append(uint8_t *msg, size_t *msg_len, size_t msg_max_len,
                     const knot_rrset_t *tsig_rr);

179 180 181
/*! \brief Return true if the TSIG RCODE allows signing the packet.
 *  \todo Proper documentation.
 */
182
static inline bool knot_tsig_can_sign(uint16_t tsig_rcode) {
183
	return tsig_rcode == KNOT_RCODE_NOERROR || tsig_rcode == KNOT_RCODE_BADTIME;
184 185
}

186
/*! @} */