summaryrefslogtreecommitdiffstats
path: root/src/lib/d2srv/testutils/nc_test_utils.h
blob: 73b6287624c1906c16f60c264ae2d286be58d75d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
// Copyright (C) 2013-2021 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

#ifndef NC_TEST_UTILS_H
#define NC_TEST_UTILS_H

/// @file nc_test_utils.h prototypes for functions related transaction testing.

#include <asiolink/io_service.h>
#include <asiolink/interval_timer.h>
#include <d2srv/d2_update_message.h>
#include <d2srv/nc_trans.h>

#include <boost/asio/ip/udp.hpp>
#include <boost/asio/socket_base.hpp>
#include <gtest/gtest.h>

namespace isc {
namespace d2 {

extern const char* valid_d2_config;
extern const char* TEST_DNS_SERVER_IP;
extern size_t TEST_DNS_SERVER_PORT;

// Not extern'ed to allow use as array size
const int TEST_MSG_MAX = 1024;

typedef boost::shared_ptr<boost::asio::ip::udp::socket> SocketPtr;

/// @brief This class simulates a DNS server.  It is capable of performing
/// an asynchronous read, governed by an IOService, and responding to received
/// requests in a given manner.
class FauxServer {
public:
    /// @brief The types of response generated by the server.
    enum ResponseMode {
        USE_RCODE,    // Generate a response with a given RCODE
        CORRUPT_RESP, // Generate a corrupt response
        INVALID_TSIG  // Generate a response with the wrong TSIG key
    };

    /// @brief Reference to IOService to use for IO processing.
    asiolink::IOService& io_service_;

    /// @brief IP address at which to listen for requests.
    const asiolink::IOAddress& address_;

    /// @brief Port on which to listen for requests.
    size_t port_;

    /// @brief Socket on which listening is done.
    SocketPtr server_socket_;

    /// @brief Stores the end point of requesting client.
    boost::asio::ip::udp::endpoint remote_;

    /// @brief Buffer in which received packets are stuffed.
    uint8_t receive_buffer_[TEST_MSG_MAX];

    /// @brief Flag which indicates if a receive has been initiated but not yet
    /// completed.
    bool receive_pending_;
    /// @brief Flag which indicates if server is in perpetual receive mode.
    /// If true once a receive has been completed, a new one will be
    /// automatically initiated.
    bool perpetual_receive_;

    /// @brief TSIG Key to use to verify requests and sign responses. If it is
    /// NULL TSIG is not used.
    D2TsigKeyPtr tsig_key_;

    /// @brief Constructor
    ///
    /// @param io_service IOService to be used for socket IO.
    /// @param address  IP address at which the server should listen.
    /// @param port Port number at which the server should listen.
    FauxServer(asiolink::IOService& io_service, asiolink::IOAddress& address,
               size_t port);

    /// @brief Constructor
    ///
    /// @param io_service IOService to be used for socket IO.
    /// @param server DnsServerInfo of server the DNS server. This supplies the
    /// server's ip address and port.
    FauxServer(asiolink::IOService& io_service, DnsServerInfo& server);

    /// @brief Destructor
    virtual ~FauxServer();

    /// @brief Initiates an asynchronous receive
    ///
    /// Starts the server listening for requests.  Upon completion of the
    /// listen, the callback method, requestHandler, is invoked.
    ///
    /// @param response_mode Selects how the server responds to a request
    /// @param response_rcode The Rcode value set in the response. Not used
    /// for all modes.
    void receive (const ResponseMode& response_mode,
                  const dns::Rcode& response_rcode=dns::Rcode::NOERROR());

    /// @brief Socket IO Completion callback
    ///
    /// This method servers as the Server's UDP socket receive callback handler.
    /// When the receive completes the handler is invoked with the parameters
    /// listed.
    ///
    /// @param error result code of the receive (determined by asio layer)
    /// @param bytes_recvd number of bytes received, if any
    /// @param response_mode type of response the handler should produce
    /// @param response_rcode value of Rcode in the response constructed by
    /// handler
    void requestHandler(const boost::system::error_code& error,
                        std::size_t bytes_recvd,
                        const ResponseMode& response_mode,
                        const dns::Rcode& response_rcode);

    /// @brief Returns true if a receive has been started but not completed.
    bool isReceivePending() {
        return receive_pending_;
    }

    /// @brief Sets the TSIG key to the given value.
    ///
    /// @param tsig_key Pointer to the TSIG key to use.  If the pointer is
    /// empty, TSIG will not be used.
    void setTSIGKey(const D2TsigKeyPtr& tsig_key) {
        tsig_key_ = tsig_key;
    }
};

/// @brief Provides a means to process IOService IO for a finite amount of time.
///
/// This class instantiates an IOService provides a single method, runTimedIO
/// which will run the IOService for no more than a finite amount of time,
/// at least one event is executed or the IOService is stopped.
/// It provides an virtual handler for timer expiration event.  It is
/// intended to be used as a base class for test fixtures that need to process
/// IO by providing them a consistent way to do so while retaining a safety
/// valve so tests do not hang.
class TimedIO  {
public:
    asiolink::IOServicePtr io_service_;
    asiolink::IntervalTimer timer_;
    int run_time_;

    /// @brief Constructor
    TimedIO();

    /// @brief Destructor
    virtual ~TimedIO();

    /// @brief IO Timer expiration handler
    ///
    /// Stops the IOService and fails the current test.
    virtual void timesUp();

    /// @brief Processes IO till time expires or at least one handler executes.
    ///
    /// This method first polls IOService to run any ready handlers.  If no
    /// handlers are ready, it starts the internal time to run for the given
    /// amount of time and invokes service's run_one method.  This method
    /// blocks until at least one handler executes or the IO Service is stopped.
    /// Upon completion of this method the timer is cancelled.  Should the
    /// timer expires prior to run_one returning, the timesUp handler will be
    /// invoked which stops the IO service and fails the test.
    ///
    /// Note that this method closely mimics the runIO method in D2Process.
    ///
    /// @param run_time maximum length of time to run in milliseconds before
    /// timing out.
    ///
    /// @return Returns the number of handlers executed or zero. A return of
    /// zero indicates that the IOService has been stopped.
    int runTimedIO(int run_time);

};

/// @brief Base class Test fixture for testing transactions.
class TransactionTest : public TimedIO,  public ::testing::Test {
public:
    dhcp_ddns::NameChangeRequestPtr ncr_;
    DdnsDomainPtr forward_domain_;
    DdnsDomainPtr reverse_domain_;
    D2CfgMgrPtr cfg_mgr_;

    /// @brief constants used to specify change directions for a transaction.
    static const unsigned int FORWARD_CHG;      // Only forward change.
    static const unsigned int REVERSE_CHG;      // Only reverse change.
    static const unsigned int FWD_AND_REV_CHG;  // Both forward and reverse.

    TransactionTest();
    virtual ~TransactionTest();

    /// @brief Creates a transaction which requests an IPv4 DNS update.
    ///
    /// The transaction is constructed around a predefined (i.e. "canned")
    /// IPv4 NameChangeRequest. The request has both forward and reverse DNS
    /// changes requested.  Based upon the change mask, the transaction
    /// will have either the forward, reverse, or both domains populated.
    ///
    /// @param change_type selects the type of change requested, CHG_ADD or
    /// CHG_REMOVE.
    /// @param change_mask determines which change directions are requested
    /// FORWARD_CHG, REVERSE_CHG, or FWD_AND_REV_CHG.
    /// @param tsig_key_info pointer to the TSIGKeyInfo to assign to both
    /// domains in the transaction.  This will cause the transaction to
    /// use TSIG.  If the pointer is empty, TSIG will not be used.
    void setupForIPv4Transaction(dhcp_ddns::NameChangeType change_type,
                                 int change_mask,
                                 const TSIGKeyInfoPtr& tsig_key_info =
                                 TSIGKeyInfoPtr());

    /// @brief Creates a transaction which requests an IPv4 DNS update.
    ///
    /// Convenience wrapper around the above method which accepts a string
    /// key_name from which the TSIGKeyInfo is constructed.  Note the string
    /// may not be blank.
    ///
    /// @param change_type selects the type of change requested, CHG_ADD or
    /// CHG_REMOVE.
    /// @param change_mask determines which change directions are requested
    /// FORWARD_CHG, REVERSE_CHG, or FWD_AND_REV_CHG.
    /// @param key_name value to use to create TSIG key. The value may not
    /// be blank.
    void setupForIPv4Transaction(dhcp_ddns::NameChangeType change_type,
                                 int change_mask, const std::string& key_name);

    /// @brief Creates a transaction which requests an IPv6 DNS update.
    ///
    /// The transaction is constructed around a predefined (i.e. "canned")
    /// IPv6 NameChangeRequest. The request has both forward and reverse DNS
    /// changes requested.  Based upon the change mask, the transaction
    /// will have either the forward, reverse, or both domains populated.
    ///
    /// @param change_type selects the type of change requested, CHG_ADD or
    /// CHG_REMOVE.
    /// @param change_mask determines which change directions are requested
    /// FORWARD_CHG, REVERSE_CHG, or FWD_AND_REV_CHG.
    /// @param tsig_key_info pointer to the TSIGKeyInfo to assign to both
    /// domains in the transaction.  This will cause the transaction to
    /// use TSIG.  If the pointer is empty, TSIG will not be used.
    void setupForIPv6Transaction(dhcp_ddns::NameChangeType change_type,
                                 int change_mask,
                                 const TSIGKeyInfoPtr& tsig_key_info =
                                 TSIGKeyInfoPtr());

    /// @brief Creates a transaction which requests an IPv6 DNS update.
    ///
    /// Convenience wrapper around the above method which accepts a string
    /// key_name from which the TSIGKeyInfo is constructed.  Note the string
    /// may not be blank.
    ///
    /// @param change_type selects the type of change requested, CHG_ADD or
    /// CHG_REMOVE.
    /// @param change_mask determines which change directions are requested
    /// FORWARD_CHG, REVERSE_CHG, or FWD_AND_REV_CHG.
    /// @param key_name value to use to create TSIG key, if blank TSIG will not
    /// be used.
    void setupForIPv6Transaction(dhcp_ddns::NameChangeType change_type,
                                 int change_mask, const std::string& key_name);
};


/// @brief Tests the number of RRs in a request section against a given count.
///
/// This function actually returns the number of RRsetPtrs in a section. Since
/// D2 only uses RRsets with a single RData in each (i.e. 1 RR), it is used
/// as the number of RRs.  The dns::Message::getRRCount() cannot be used for
/// this as it returns the number of RDatas in an RRSet which does NOT equate
/// to the number of RRs. RRs with no RData, those with class or type of ANY,
/// are not counted.
///
/// @param request DNS update request to test
/// @param section enum value of the section to count
/// @param count the expected number of RRs
extern void checkRRCount(const D2UpdateMessagePtr& request,
                         D2UpdateMessage::UpdateMsgSection section, int count);

/// @brief Tests the zone content of a given request.
///
/// @param request DNS update request to validate
/// @param exp_zone_name expected value of the zone name in the zone section
extern void checkZone(const D2UpdateMessagePtr& request,
                      const std::string& exp_zone_name);

/// @brief Tests the contents of an RRset
///
/// @param rrset Pointer the RRset to test
/// @param exp_name expected value of RRset name (FQDN or reverse ip)
/// @param exp_class expected RRClass value of RRset
/// @param exp_typ expected RRType value of RRset
/// @param exp_ttl  expected TTL value of RRset
/// @param ncr NameChangeRequest on which the RRset is based
/// @param has_rdata if true, RRset's rdata will be checked based on it's
/// RRType.  Set this to false if the RRset's type supports Rdata but it does
/// not contain it.  For instance, prerequisites of type NONE have no Rdata
/// where updates of type NONE may.
extern void checkRR(dns::RRsetPtr rrset, const std::string& exp_name,
                    const dns::RRClass& exp_class, const dns::RRType& exp_type,
                    unsigned int exp_ttl, dhcp_ddns::NameChangeRequestPtr ncr,
                    bool has_rdata=true);

/// @brief Fetches an RR(set) from a given section of a request
///
/// @param request DNS update request from which the RR should come
/// @param section enum value of the section from which the RR should come
/// @param index zero-based index of the RR of interest.
///
/// @return Pointer to the RR of interest, empty pointer if the index is out
/// of range.
extern dns::RRsetPtr getRRFromSection(const D2UpdateMessagePtr& request,
                                      D2UpdateMessage::UpdateMsgSection section,
                                      int index);
/// @brief Creates a NameChangeRequest from a JSON string
///
/// @param ncr_str JSON string form of a NameChangeRequest.  Example:
/// @code
///        const char* msg_str =
///            "{"
///            " \"change-type\" : 0 , "
///            " \"forward-change\" : true , "
///            " \"reverse-change\" : true , "
///            " \"fqdn\" : \"my.example.com.\" , "
///            " \"ip-address\" : \"192.168.2.1\" , "
///            " \"dhcid\" : \"0102030405060708\" , "
///            " \"lease-expires-on\" : \"20130121132405\" , "
///            " \"lease-length\" : 1300 "
///            "}";
///
/// @endcode

/// @brief Verifies a forward mapping addition DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// adding a forward DNS mapping.
///
/// @param tran Transaction containing the request to be verified.
extern void checkAddFwdAddressRequest(NameChangeTransaction& tran);

/// @brief Verifies a forward mapping replacement DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// replacing a forward DNS mapping.
///
/// @param tran Transaction containing the request to be verified.
extern void checkReplaceFwdAddressRequest(NameChangeTransaction& tran);

/// @brief Verifies a reverse mapping replacement DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// replacing a reverse DNS mapping.
///
/// @param tran Transaction containing the request to be verified.
extern void checkReplaceRevPtrsRequest(NameChangeTransaction& tran);

/// @brief Verifies a forward address removal DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// removing the forward address DNS entry.
///
/// @param tran Transaction containing the request to be verified.
extern void checkRemoveFwdAddressRequest(NameChangeTransaction& tran);

/// @brief Verifies a forward RR removal DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// removing forward RR DNS entries.
///
/// @param tran Transaction containing the request to be verified.
extern void checkRemoveFwdRRsRequest(NameChangeTransaction& tran);

/// @brief Verifies a reverse mapping removal DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// removing a reverse DNS mapping.
///
/// @param tran Transaction containing the request to be verified.
extern void checkRemoveRevPtrsRequest(NameChangeTransaction& tran);

/// @brief Verifies a simple forward mapping replacement DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// replacing a forward DNS mapping when not using conflict resolution.
///
/// @param tran Transaction containing the request to be verified.
extern void checkSimpleReplaceFwdAddressRequest(NameChangeTransaction& tran);

/// @brief Verifies a simple forward RR removal DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// removing forward RR DNS entries when not using conflict resolution.
///
/// @param tran Transaction containing the request to be verified.
extern void checkSimpleRemoveFwdRRsRequest(NameChangeTransaction& tran);

/// @brief Verifies a simple reverse RR removal DNS update request
///
/// Tests that the DNS Update request for a given transaction, is correct for
/// removing reverse RR DNS entries when not using conflict resolution.
///
/// @param tran Transaction containing the request to be verified.
extern void  checkSimpleRemoveRevPtrsRequest(NameChangeTransaction& tran);

/// @brief Creates a NameChangeRequest from JSON string.
///
/// @param ncr_str string of JSON text from which to make the request.
///
/// @return Pointer to newly created request.
///
/// @throw Underlying methods may throw.
extern
dhcp_ddns::NameChangeRequestPtr makeNcrFromString(const std::string& ncr_str);

/// @brief Creates a DdnsDomain with the one server.
///
/// @param zone_name zone name of the domain
/// @param key_name TSIG key name of the TSIG key for this domain. It will
/// create a TSIGKeyInfo based on the key_name and assign it to the domain.
///
/// @throw Underlying methods may throw.
extern DdnsDomainPtr makeDomain(const std::string& zone_name,
                                const std::string& key_name);

/// @brief Creates a DdnsDomain with the one server.
///
/// @param zone_name zone name of the domain
/// @param tsig_key_info pointer to the TSIGInfog key for this domain.
/// Defaults to an empty pointer, meaning this domain has no key.
///
/// @throw Underlying methods may throw.
extern DdnsDomainPtr makeDomain(const std::string& zone_name,
                                const TSIGKeyInfoPtr&
                                tsig_key_info = TSIGKeyInfoPtr());

/// @brief Creates a TSIGKeyInfo
///
/// @param key_name name of the key
/// @param secret key secret data as a base64 encoded string. If blank,
/// then the secret value will be generated from key_name.
/// @param algorithm algorithm to use. Defaults to MD5.
/// @return a TSIGKeyInfoPtr for the newly created key.  If key_name is blank
/// the pointer will be empty.
/// @throw Underlying methods may throw.
extern
TSIGKeyInfoPtr makeTSIGKeyInfo(const std::string& key_name,
                               const std::string& secret = "",
                               const std::string& algorithm
                               = TSIGKeyInfo::HMAC_MD5_STR);

/// @brief Creates a DnsServerInfo and adds it to the given DdnsDomain.
///
/// The server is created and added to the domain, without duplicate entry
/// checking.
///
/// @param domain DdnsDomain to which to add the server
/// @param name new server's host name of the server
/// @param ip new server's ip address
/// @param port new server's port
/// @param tsig_key_info pointer to the TSIGInfog key for this server.
/// Defaults to an empty pointer, meaning this server has no key.
///
/// @throw Underlying methods may throw.
extern void addDomainServer(DdnsDomainPtr& domain, const std::string& name,
                            const std::string& ip = TEST_DNS_SERVER_IP,
                            const size_t port = TEST_DNS_SERVER_PORT,
                            const TSIGKeyInfoPtr&
                            tsig_key_info = TSIGKeyInfoPtr());

/// @brief Creates a hex text dump of the given data buffer.
///
/// This method is not used for testing but is handy for debugging.  It creates
/// a pleasantly formatted string of 2-digits per byte separated by spaces with
/// 16 bytes per line.
///
/// @param data pointer to the data to dump
/// @param len size (in bytes) of data
extern std::string toHexText(const uint8_t* data, size_t len);

/// @brief Verifies the current state and next event in a transaction
/// @param trans NameChangeTransaction to check
/// @param exp_state expected current state of the transaction
/// @param exp_event  expected next event of the transaction
/// @param file source file name
/// @param line source line number
extern void checkContext(NameChangeTransactionPtr trans, const int exp_state,
                         const int exp_evt, const std::string& file, int line);

/// @brief Macro for calling checkContext() that supplies invocation location
#define CHECK_CONTEXT(a,b,c) checkContext(a,b,c,__FILE__,__LINE__)

} // namespace isc::d2
} // namespace isc

#endif