Branch data Line data Source code
1 : : // Copyright (C) 2012 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 __NSEC3HASH_H
16 : : #define __NSEC3HASH_H 1
17 : :
18 : : #include <string>
19 : :
20 : : #include <exceptions/exceptions.h>
21 : :
22 : : namespace isc {
23 : : namespace dns {
24 : : class Name;
25 : :
26 : : namespace rdata {
27 : : namespace generic {
28 : : class NSEC3;
29 : : class NSEC3PARAM;
30 : : }
31 : : }
32 : :
33 : : /// \brief An exception that is thrown for when an \c NSEC3Hash object is
34 : : /// constructed with an unknown hash algorithm.
35 : : ///
36 : : /// A specific exception class is used so that the caller can selectively
37 : : /// catch this exception, e.g., while loading a zone, and handle it
38 : : /// accordingly.
39 : 4 : class UnknownNSEC3HashAlgorithm : public isc::Exception {
40 : : public:
41 : : UnknownNSEC3HashAlgorithm(const char* file, size_t line,
42 : : const char* what) :
43 : 8 : isc::Exception(file, line, what) {}
44 : : };
45 : :
46 : : /// \brief A calculator of NSEC3 hashes.
47 : : ///
48 : : /// This is an abstract base class that defines a simple interface to
49 : : /// calculating NSEC3 hash values as defined in RFC5155.
50 : : ///
51 : : /// (Derived classes of) this class is designed to be "stateless" in that it
52 : : /// basically doesn't hold mutable state once constructed, and hash
53 : : /// calculation solely depends on the parameters given on construction and
54 : : /// input to the \c calculate() method. In that sense this could be a
55 : : /// single free function rather than a class, but we decided to provide the
56 : : /// functionality as a class for two reasons: NSEC3 hash calculations would
57 : : /// often take place more than one time in a single query or validation
58 : : /// process, so it would be more efficient if we could hold some internal
59 : : /// resources used for the calculation and reuse it over multiple calls to
60 : : /// \c calculate() (a concrete implementation in this library actually does
61 : : /// this); Second, we may want to customize the hash calculation logic for
62 : : /// testing purposes or for other future extensions. For example, we may
63 : : /// want to use a fake calculator for tests that returns pre-defined hash
64 : : /// values (so a slight change to the test input wouldn't affect the test
65 : : /// result). Using classes from this base would make it possible more
66 : : /// transparently to the application.
67 : : ///
68 : : /// A specific derived class instance must be created by the factory method,
69 : : /// \c create().
70 : : ///
71 : : /// There can be several ways to extend this class in future. Those include:
72 : : /// - Allow customizing the factory method so the application change the
73 : : /// behavior dynamically.
74 : : /// - Allow to construct the class from a tuple of parameters, that is,
75 : : /// integers for algorithm, iterations and flags, and opaque salt data.
76 : : /// For example, we might want to use that version for validators.
77 : : /// - Allow producing hash value as binary data
78 : : /// - Allow updating NSEC3 parameters of a class object so we can still reuse
79 : : /// the internal resources for different sets of parameters.
80 : : class NSEC3Hash {
81 : : protected:
82 : : /// \brief The default constructor.
83 : : ///
84 : : /// This is defined as protected to prevent this class from being directly
85 : : /// instantiated even if the class definition is modified (accidentally
86 : : /// or intentionally) to have no pure virtual methods.
87 : 75 : NSEC3Hash() {}
88 : :
89 : : public:
90 : : /// \brief Factory method of NSECHash from NSEC3PARAM RDATA.
91 : : ///
92 : : /// The hash algorithm given via \c param must be known to the
93 : : /// implementation. Otherwise \c UnknownNSEC3HashAlgorithm exception
94 : : /// will be thrown.
95 : : ///
96 : : /// This method creates an \c NSEC3Hash object using \c new. The caller
97 : : /// is responsible for releasing it with \c delete that is compatible to
98 : : /// the one used in this library. In practice, the application would
99 : : /// generally need to store the returned pointer in some form of smart
100 : : /// pointer; otherwise the resulting code will be quite fragile against
101 : : /// exceptions (and in this case the application doesn't have to worry
102 : : /// about explicit \c delete).
103 : : ///
104 : : /// \throw UnknownNSEC3HashAlgorithm The specified algorithm in \c param
105 : : /// is unknown.
106 : : /// \throw std::bad_alloc Internal resource allocation failure.
107 : : ///
108 : : /// \param param NSEC3 parameters used for subsequent calculation.
109 : : /// \return A pointer to a concrete derived object of \c NSEC3Hash.
110 : : static NSEC3Hash* create(const rdata::generic::NSEC3PARAM& param);
111 : :
112 : : /// \brief Factory method of NSECHash from NSEC3 RDATA.
113 : : ///
114 : : /// This is similar to the other version, but extracts the parameters
115 : : /// for hash calculation from an NSEC3 RDATA object.
116 : : static NSEC3Hash* create(const rdata::generic::NSEC3& nsec3);
117 : :
118 : : /// \brief The destructor.
119 : 75 : virtual ~NSEC3Hash() {}
120 : :
121 : : /// \brief Calculate the NSEC3 hash.
122 : : ///
123 : : /// This method calculates the NSEC3 hash value for the given \c name
124 : : /// with the hash parameters (algorithm, iterations and salt) given at
125 : : /// construction, and returns the value as a base32hex-encoded string
126 : : /// (without containing any white spaces). All US-ASCII letters in the
127 : : /// string will be upper cased.
128 : : ///
129 : : /// \param name The domain name for which the hash value is to be
130 : : /// calculated.
131 : : /// \return Base32hex-encoded string of the hash value.
132 : : virtual std::string calculate(const Name& name) const = 0;
133 : :
134 : : /// \brief Match given NSEC3 parameters with that of the hash.
135 : : ///
136 : : /// This method compares NSEC3 parameters used for hash calculation
137 : : /// in the object with those in the given NSEC3 RDATA, and return
138 : : /// true iff they completely match. In the current implementation
139 : : /// only the algorithm, iterations and salt are compared; the flags
140 : : /// are ignored (as they don't affect hash calculation per RFC5155).
141 : : ///
142 : : /// \throw None
143 : : ///
144 : : /// \param nsec3 An NSEC3 RDATA object whose hash parameters are to be
145 : : /// matched
146 : : /// \return true If the given parameters match the local ones; false
147 : : /// otherwise.
148 : : virtual bool match(const rdata::generic::NSEC3& nsec3) const = 0;
149 : :
150 : : /// \brief Match given NSEC3PARAM parameters with that of the hash.
151 : : ///
152 : : /// This is similar to the other version, but extracts the parameters
153 : : /// to compare from an NSEC3PARAM RDATA object.
154 : : virtual bool match(const rdata::generic::NSEC3PARAM& nsec3param) const = 0;
155 : : };
156 : :
157 : : /// \brief Factory class of NSEC3Hash.
158 : : ///
159 : : /// This class is an abstract base class that provides the creation interfaces
160 : : /// of \c NSEC3Hash objects. By defining a specific derived class of the
161 : : /// creator, normally with a different specific class of \c NSEC3Hash,
162 : : /// the application can use a customized implementation of \c NSEC3Hash
163 : : /// without changing the library itself. The intended primary application of
164 : : /// such customization is tests (it would be convenient for a test to produce
165 : : /// a faked hash value regardless of the input so it doesn't have to identify
166 : : /// a specific input value to produce a particular hash). Another possibility
167 : : /// would be an experimental extension for a newer hash algorithm or
168 : : /// implementation.
169 : : ///
170 : : /// The two main methods named \c create() correspond to the static factory
171 : : /// methods of \c NSEC3Hash of the same name.
172 : : ///
173 : : /// By default, the library uses the \c DefaultNSEC3HashCreator creator.
174 : : /// The \c setNSEC3HashCreator() function can be used to replace it with a
175 : : /// user defined version. For such customization purposes as implementing
176 : : /// experimental new hash algorithms, the application may internally want to
177 : : /// use the \c DefaultNSEC3HashCreator in general cases while creating a
178 : : /// customized type of \c NSEC3Hash object for that particular hash algorithm.
179 : : ///
180 : : /// The creator objects are generally expected to be stateless; they will
181 : : /// only encapsulate the factory logic. The \c create() methods are declared
182 : : /// as const member functions for this reason. But if we see the need for
183 : : /// having a customized creator that benefits from its own state in future,
184 : : /// this condition can be loosened.
185 : : class NSEC3HashCreator {
186 : : protected:
187 : : /// \brief The default constructor.
188 : : ///
189 : : /// Make very sure this isn't directly instantiated by making it protected
190 : : /// even if this class is modified to lose all pure virtual methods.
191 : 219 : NSEC3HashCreator() {}
192 : :
193 : : public:
194 : : /// \brief The destructor.
195 : : ///
196 : : /// This does nothing; defined only for allowing derived classes to
197 : : /// specialize its behavior.
198 : 217 : virtual ~NSEC3HashCreator() {}
199 : :
200 : : /// \brief Factory method of NSECHash from NSEC3PARAM RDATA.
201 : : ///
202 : : /// See
203 : : /// <code>NSEC3Hash::create(const rdata::generic::NSEC3PARAM& param)</code>
204 : : virtual NSEC3Hash* create(const rdata::generic::NSEC3PARAM& nsec3param)
205 : : const = 0;
206 : :
207 : : /// \brief Factory method of NSECHash from NSEC3 RDATA.
208 : : ///
209 : : /// See
210 : : /// <code>NSEC3Hash::create(const rdata::generic::NSEC3& param)</code>
211 : : virtual NSEC3Hash* create(const rdata::generic::NSEC3& nsec3)
212 : : const = 0;
213 : : };
214 : :
215 : : /// \brief The default NSEC3Hash creator.
216 : : ///
217 : : /// This derived class implements the \c NSEC3HashCreator interfaces for
218 : : /// the standard NSEC3 hash calculator as defined in RFC5155. The library
219 : : /// will use this creator by default, so normal applications don't have to
220 : : /// be aware of this class at all. This class is publicly visible for the
221 : : /// convenience of special applications that want to customize the creator
222 : : /// behavior for a particular type of parameters while preserving the default
223 : : /// behavior for others.
224 : 4 : class DefaultNSEC3HashCreator : public NSEC3HashCreator {
225 : : public:
226 : : virtual NSEC3Hash* create(const rdata::generic::NSEC3PARAM& param) const;
227 : : virtual NSEC3Hash* create(const rdata::generic::NSEC3& nsec3) const;
228 : : };
229 : :
230 : : /// \brief The registrar of \c NSEC3HashCreator.
231 : : ///
232 : : /// This function sets or resets the system-wide \c NSEC3HashCreator that
233 : : /// is used by \c NSEC3Hash::create().
234 : : ///
235 : : /// If \c new_creator is non NULL, the given creator object will replace
236 : : /// any existing creator. If it's NULL, the default builtin creator will be
237 : : /// used again from that point.
238 : : ///
239 : : /// When \c new_creator is non NULL, the caller is responsible for keeping
240 : : /// the referenced object valid as long as it can be used via
241 : : /// \c NSEC3Hash::create().
242 : : ///
243 : : /// \exception None
244 : : /// \param new_creator A pointer to the new creator object or NULL.
245 : : void setNSEC3HashCreator(const NSEC3HashCreator* new_creator);
246 : :
247 : : }
248 : : }
249 : : #endif // __NSEC3HASH_H
250 : :
251 : : // Local Variables:
252 : : // mode: c++
253 : : // End:
|
