Branch data Line data Source code
1 : : // Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC")
2 : : //
3 : : // Permission to use, copy, modify, and/or distribute this software for any
4 : : // purpose with or without fee is hereby granted, provided that the above
5 : : // copyright notice and this permission notice appear in all copies.
6 : : //
7 : : // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8 : : // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9 : : // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
10 : : // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
11 : : // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
12 : : // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
13 : : // PERFORMANCE OF THIS SOFTWARE.
14 : :
15 : : #ifndef __TSIGRECORD_H
16 : : #define __TSIGRECORD_H 1
17 : :
18 : : #include <ostream>
19 : : #include <string>
20 : :
21 : : #include <boost/shared_ptr.hpp>
22 : :
23 : : #include <util/buffer.h>
24 : :
25 : : #include <dns/name.h>
26 : : #include <dns/rdataclass.h>
27 : :
28 : : namespace isc {
29 : : namespace util {
30 : : class OutputBuffer;
31 : : }
32 : : namespace dns {
33 : : class AbstractMessageRenderer;
34 : :
35 : : /// TSIG resource record.
36 : : ///
37 : : /// A \c TSIGRecord class object represents a TSIG resource record and is
38 : : /// responsible for conversion to and from wire format TSIG record based on
39 : : /// the protocol specification (RFC2845).
40 : : /// This class is provided so that other classes and applications can handle
41 : : /// TSIG without knowing protocol details of TSIG, such as that it uses a
42 : : /// fixed constant of TTL.
43 : : ///
44 : : /// \todo So the plan is to eventually provide the "from wire" constructor.
45 : : /// It's not yet provided in the current phase of development.
46 : : ///
47 : : /// \note
48 : : /// This class could be a derived class of \c AbstractRRset. That way
49 : : /// it would be able to be used in a polymorphic way; for example,
50 : : /// an application can construct a TSIG RR by itself and insert it to a
51 : : /// \c Message object as a generic RRset. On the other hand, it would mean
52 : : /// this class would have to implement an \c RdataIterator (even though it
53 : : /// can be done via straightforward forwarding) while the iterator is mostly
54 : : /// redundant since there should be one and only one RDATA for a valid TSIG
55 : : /// RR. Likewise, some methods such as \c setTTL() method wouldn't be well
56 : : /// defined due to such special rules for TSIG as using a fixed TTL.
57 : : /// Overall, TSIG is a very special RR type that simply uses the compatible
58 : : /// resource record format, and it will be unlikely that a user wants to
59 : : /// handle it through a generic interface in a polymorphic way.
60 : : /// We therefore chose to define it as a separate class. This is also
61 : : /// similar to why \c EDNS is a separate class.
62 [ + - ][ + - ]: 856 : class TSIGRecord {
63 : : public:
64 : : ///
65 : : /// \name Constructors
66 : : ///
67 : : /// We use the default copy constructor, default copy assignment operator,
68 : : /// (and default destructor) intentionally.
69 : : //@{
70 : : /// Constructor from TSIG key name and RDATA
71 : : ///
72 : : /// \exception std::bad_alloc Resource allocation for copying the name or
73 : : /// RDATA fails
74 : : TSIGRecord(const Name& key_name, const rdata::any::TSIG& tsig_rdata);
75 : :
76 : : /// Constructor from resource record (RR) parameters.
77 : : ///
78 : : /// This constructor is intended to be used in the context of parsing
79 : : /// an incoming DNS message that contains a TSIG. The parser would
80 : : /// first extract the owner name, RR type (which is TSIG) class, TTL and
81 : : /// the TSIG RDATA from the message. This constructor is expected to
82 : : /// be given these RR parameters (except the RR type, because it must be
83 : : /// TSIG).
84 : : ///
85 : : /// According to RFC2845, a TSIG RR uses fixed RR class (ANY) and TTL (0).
86 : : /// If the RR class or TTL is different from the expected one, this
87 : : /// implementation considers it an invalid record and throws an exception
88 : : /// of class \c DNSMessageFORMERR.
89 : : ///
90 : : /// \note This behavior is not specified in the protocol specification,
91 : : /// but this implementation rejects unexpected values for the following
92 : : /// reasons (but in any case, this won't matter much in practice as
93 : : /// RFC2848 clearly states these fields always have the fixed values and
94 : : /// any sane implementation of TSIG signer will follow that):
95 : : /// According to the RFC editor (in a private communication), the intended
96 : : /// use of the TSIG TTL field is to signal protocol extensions (currently
97 : : /// no such extension is defined), so this field may actually be
98 : : /// validly non 0 in future. However, until the implementation supports
99 : : /// that extension it may not always be able to handle the extended
100 : : /// TSIG as intended; the extension may even affect digest computation.
101 : : /// There's a related issue on this point. Different implementations
102 : : /// interpret the RFC in different ways on the received TTL when
103 : : /// digesting the message: BIND 9 uses the received value (even if
104 : : /// it's not 0) as part of the TSIG variables; NLnet Labs' LDNS and NSD
105 : : /// always use a fixed constant of 0 regardless of the received TTL value.
106 : : /// This means if and when an extension with non 0 TTL is introduced
107 : : /// there will be interoperability problems in the form of verification
108 : : /// failure. By explicitly rejecting it (and subsequently returning
109 : : /// a response with a format error) we can indicate the source of the
110 : : /// problem more clearly than a "bad signature" TSIG error, which can
111 : : /// happen for various reasons. On the other hand, rejecting unexpected
112 : : /// RR classes is mostly for consistency; the RFC lists these two fields
113 : : /// in the same way, so it makes more sense to handle them equally.
114 : : /// (BIND 9 rejects unexpected RR classes for TSIG, but that is part of
115 : : /// general check on RR classes on received RRs; it generally requests
116 : : /// all classes are the same, and if the protocol specifies the use of
117 : : /// a particular class for a particular type of RR, it requests that
118 : : /// class be used).
119 : : ///
120 : : /// Likewise, if \c rdata is not of type \c any::TSIG, an exception of
121 : : /// class DNSMessageFORMERR will be thrown. When the caller is a
122 : : /// DNS message parser and builds \c rdata from incoming wire format
123 : : /// data as described above, this case happens when the RR class is
124 : : /// different from ANY (in the implementation, the type check takes place
125 : : /// before the explicit check against the RR class explained in the
126 : : /// previous paragraph).
127 : : ///
128 : : /// The \c length parameter is intended to be the length of the TSIG RR
129 : : /// (from the beginning of the owner name to the end of the RDATA) when
130 : : /// the caller is a DNS message parser. Note that it is the actual length
131 : : /// for the RR in the format; if the owner name or the algorithm name
132 : : /// (in the RDATA) is compressed (although the latter should not be
133 : : /// compressed according to RFC3597), the length must be the size of the
134 : : /// compressed data. The length is recorded inside the class and will
135 : : /// be returned via subsequent calls to \c getLength(). It's intended to
136 : : /// be used in the context TSIG verification; in the verify process
137 : : /// the MAC computation must be performed for the original data without
138 : : /// TSIG, so, to avoid parsing the entire data in the verify process
139 : : /// again, it's necessary to record information that can identify the
140 : : /// length to be digested for the MAC. This parameter serves for that
141 : : /// purpose.
142 : : ///
143 : : /// \note Since the constructor doesn't take the wire format data per se,
144 : : /// it doesn't (and cannot) check the validity of \c length, and simply
145 : : /// accepts any given value. It even accepts obviously invalid values
146 : : /// such as 0. It's caller's responsibility to provide a valid value of
147 : : /// length, and, the verifier's responsibility to use the length safely.
148 : : ///
149 : : /// <b>DISCUSSION:</b> this design is fragile in that it introduces
150 : : /// a tight coupling between message parsing and TSIG verification via
151 : : /// the \c TSIGRecord class. In terms of responsibility decoupling,
152 : : /// the ideal way to have \c TSIGRecord remember the entire wire data
153 : : /// along with the length of the TSIG. Then in the TSIG verification
154 : : /// we could refer to the necessary potion of data solely from a
155 : : /// \c TSIGRecord object. However, this approach would require expensive
156 : : /// heavy copy of the original data or introduce another kind of coupling
157 : : /// between the data holder and this class (if the original data is freed
158 : : /// while a \c TSIGRecord object referencing the data still exists, the
159 : : /// result will be catastrophic). As a "best current compromise", we
160 : : /// use the current design. We may reconsider it if it turns out to
161 : : /// cause a big problem or we come up with a better idea.
162 : : ///
163 : : /// \exception DNSMessageFORMERR Given RR parameters are invalid for TSIG.
164 : : /// \exception std::bad_alloc Internal resource allocation fails.
165 : : ///
166 : : /// \param name The owner name of the TSIG RR
167 : : /// \param rrclass The RR class of the RR. Must be \c RRClass::ANY()
168 : : /// (see above)
169 : : /// \param ttl The TTL of the RR. Must be 0 (see above)
170 : : /// \param rdata The RDATA of the RR. Must be of type \c any::TSIG.
171 : : /// \param length The size of the RR (see above)
172 : : TSIGRecord(const Name& name, const RRClass& rrclass, const RRTTL& ttl,
173 : : const rdata::Rdata& rdata, size_t length);
174 : : //@}
175 : :
176 : : /// Return the owner name of the TSIG RR, which is the TSIG key name
177 : : ///
178 : : /// \exception None
179 : : const Name& getName() const { return (key_name_); }
180 : :
181 : : /// Return the RDATA of the TSIG RR
182 : : ///
183 : : /// \exception None
184 : : const rdata::any::TSIG& getRdata() const { return (rdata_); }
185 : :
186 : : /// \name Protocol constants and defaults
187 : : ///
188 : : //@{
189 : : /// Return the RR class of TSIG
190 : : ///
191 : : /// TSIG always uses the ANY RR class. This static method returns it,
192 : : /// when, though unlikely, an application wants to know which class TSIG
193 : : /// is supposed to use.
194 : : ///
195 : : /// \exception None
196 : : static const RRClass& getClass();
197 : :
198 : : /// Return the TTL value of TSIG
199 : : ///
200 : : /// TSIG always uses 0 TTL. This static method returns it,
201 : : /// when, though unlikely, an application wants to know the TTL TSIG
202 : : /// is supposed to use.
203 : : ///
204 : : /// \exception None
205 : : static const RRTTL& getTTL();
206 : : //@}
207 : :
208 : : /// Return the length of the TSIG record
209 : : ///
210 : : /// When constructed from the key name and RDATA, it is the length of
211 : : /// the record when it is rendered by the \c toWire() method.
212 : : ///
213 : : /// \note When constructed "from wire", that will mean the length of
214 : : /// the wire format data for the TSIG RR. The length will be necessary
215 : : /// to verify the message once parse is completed.
216 : : ///
217 : : /// \exception None
218 : 0 : size_t getLength() const { return (length_); }
219 : :
220 : : /// \brief Render the \c TSIG RR in the wire format.
221 : : ///
222 : : /// This method renders the TSIG record as a form of a DNS TSIG RR
223 : : /// via \c renderer, which encapsulates output buffer and other rendering
224 : : /// contexts.
225 : : ///
226 : : /// Normally this version of \c toWire() method tries to compress the
227 : : /// owner name of the RR whenever possible, but this method intentionally
228 : : /// skips owner name compression. This is due to a report that some
229 : : /// Windows clients refuse a TSIG if its owner name is compressed
230 : : /// (See http://marc.info/?l=bind-workers&m=126637138430819&w=2).
231 : : /// Reportedly this seemed to be specific to GSS-TSIG, but this
232 : : /// implementation skip compression regardless of the algorithm.
233 : : ///
234 : : /// If by adding the TSIG RR the message size would exceed the limit
235 : : /// maintained in \c renderer, this method skips rendering the RR
236 : : /// and returns 0 and mark \c renderer as "truncated" (so that a
237 : : /// subsequent call to \c isTruncated() on \c renderer will result in
238 : : /// \c true); otherwise it returns 1, which is the number of RR
239 : : /// rendered.
240 : : ///
241 : : /// \note If the caller follows the specification of adding TSIG
242 : : /// as described in RFC2845, this should not happen; the caller is
243 : : /// generally expected to leave a sufficient room in the message for
244 : : /// the TSIG. But this method checks the unexpected case nevertheless.
245 : : ///
246 : : /// \exception std::bad_alloc Internal resource allocation fails (this
247 : : /// should be rare).
248 : : ///
249 : : /// \param renderer DNS message rendering context that encapsulates the
250 : : /// output buffer and name compression information.
251 : : /// \return 1 if the TSIG RR fits in the message size limit; otherwise 0.
252 : : int toWire(AbstractMessageRenderer& renderer) const;
253 : :
254 : : /// \brief Render the \c TSIG RR in the wire format.
255 : : ///
256 : : /// This method is same as \c toWire(AbstractMessageRenderer&)const
257 : : /// except it renders the RR in an \c OutputBuffer and therefore
258 : : /// does not care about message size limit.
259 : : /// As a consequence it always returns 1.
260 : : int toWire(isc::util::OutputBuffer& buffer) const;
261 : :
262 : : /// Convert the TSIG record to a string.
263 : : ///
264 : : /// The output format is the same as the result of \c toText() for
265 : : /// other normal types of RRsets (with always using the same RR class
266 : : /// and TTL). It also ends with a newline.
267 : : ///
268 : : /// \exception std::bad_alloc Internal resource allocation fails (this
269 : : /// should be rare).
270 : : ///
271 : : /// \return A string representation of \c TSIG record
272 : : std::string toText() const;
273 : :
274 : : /// The TTL value to be used in TSIG RRs.
275 : : static const uint32_t TSIG_TTL = 0;
276 : : //@}
277 : :
278 : : private:
279 : : const Name key_name_;
280 : : const rdata::any::TSIG rdata_;
281 : : const size_t length_;
282 : : };
283 : :
284 : : /// A pointer-like type pointing to a \c TSIGRecord object.
285 : : typedef boost::shared_ptr<TSIGRecord> TSIGRecordPtr;
286 : :
287 : : /// A pointer-like type pointing to an immutable \c TSIGRecord object.
288 : : typedef boost::shared_ptr<const TSIGRecord> ConstTSIGRecordPtr;
289 : :
290 : : /// Insert the \c TSIGRecord as a string into stream.
291 : : ///
292 : : /// This method convert \c record into a string and inserts it into the
293 : : /// output stream \c os.
294 : : ///
295 : : /// \param os A \c std::ostream object on which the insertion operation is
296 : : /// performed.
297 : : /// \param record A \c TSIGRecord object output by the operation.
298 : : /// \return A reference to the same \c std::ostream object referenced by
299 : : /// parameter \c os after the insertion operation.
300 : : std::ostream& operator<<(std::ostream& os, const TSIGRecord& record);
301 : : }
302 : : }
303 : :
304 : : #endif // __TSIGRECORD_H
305 : :
306 : : // Local Variables:
307 : : // mode: c++
308 : : // End:
|
