Branch data Line data Source code
1 : : // Copyright (C) 2009 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 __TIME_UTILITIES_H
16 : : #define __TIME_UTILITIES_H 1
17 : :
18 : : #include <string>
19 : :
20 : : #include <sys/types.h>
21 : : #include <stdint.h>
22 : :
23 : : #include <exceptions/exceptions.h>
24 : :
25 : : //
26 : : // Note: this helper module isn't specific to the DNS protocol per se.
27 : : // We should probably move this to somewhere else, possibly in some common
28 : : // utility area.
29 : : //
30 : :
31 : : namespace isc {
32 : : namespace util {
33 : :
34 : : ///
35 : : /// \brief A standard DNS (or ISC) module exception that is thrown if
36 : : /// a time conversion function encounters bad input
37 : : ///
38 : 17 : class InvalidTime : public Exception {
39 : : public:
40 : 17 : InvalidTime(const char* file, size_t line, const char* what) :
41 : 17 : isc::Exception(file, line, what) {}
42 : : };
43 : :
44 : : namespace detail {
45 : : /// Return the current time in seconds
46 : : ///
47 : : /// This function returns the "current" time in seconds from epoch
48 : : /// (00:00:00 January 1, 1970) as a 64-bit signed integer. The return
49 : : /// value can represent a point of time before epoch as a negative number.
50 : : ///
51 : : /// This function is provided to help test time conscious implementations
52 : : /// such as DNSSEC and TSIG signatures. It is difficult to test them with
53 : : /// an unusual or a specifically chosen "current" via system-provided
54 : : /// library functions to get time. This function acts as a straightforward
55 : : /// wrapper of such a library function, but provides test code with a hook
56 : : /// to return an arbitrary time value: if \c isc::util::detail::gettimeFunction
57 : : /// is set to a pointer of function that returns 64-bit signed integer,
58 : : /// \c gettimeWrapper() calls that function instead of the system library.
59 : : ///
60 : : /// This hook variable is specifically intended for testing purposes, so,
61 : : /// even if it's visible outside of this library, it's not even declared in a
62 : : /// header file.
63 : : ///
64 : : /// If the implementation doesn't need to be tested with faked current time,
65 : : /// it should simply use the system supplied library function instead of
66 : : /// this one.
67 : : int64_t gettimeWrapper();
68 : : }
69 : :
70 : : ///
71 : : /// \name DNSSEC time conversion functions.
72 : : ///
73 : : /// These functions convert between times represented in seconds (in integer)
74 : : /// since epoch and those in the textual form used in the RRSIG records.
75 : : /// For integers we provide both 32-bit and 64-bit versions.
76 : : /// The RRSIG expiration and inception fields are both 32-bit unsigned
77 : : /// integers, so 32-bit versions would be more useful for protocol operations.
78 : : /// However, with 32-bit integers we need to take into account wrap-around
79 : : /// points and compare values using the serial number arithmetic as specified
80 : : /// in RFC4034, which would be more error prone. We therefore provide 64-bit
81 : : /// versions, too.
82 : : ///
83 : : /// The timezone is always UTC for these functions.
84 : : //@{
85 : : /// Convert textual DNSSEC time to integer, 64-bit version.
86 : : ///
87 : : /// The textual form must only consist of digits and be in the form of
88 : : /// YYYYMMDDHHmmSS, where:
89 : : /// - YYYY must be between 1970 and 9999
90 : : /// - MM must be between 01 and 12
91 : : /// - DD must be between 01 and 31 and must be a valid day for the month
92 : : /// represented in 'MM'. For example, if MM is 04, DD cannot be 31.
93 : : /// DD can be 29 when MM is 02 only when YYYY is a leap year.
94 : : /// - HH must be between 00 and 23
95 : : /// - mm must be between 00 and 59
96 : : /// - SS must be between 00 and 60
97 : : ///
98 : : /// For all fields the range includes the begin and end values. Note that
99 : : /// 60 is allowed for 'SS', intending a leap second, although in real operation
100 : : /// it's unlikely to be specified.
101 : : ///
102 : : /// If the given text is valid, this function converts it to an unsigned
103 : : /// 64-bit number of seconds since epoch (1 January 1970 00:00:00) and returns
104 : : /// the converted value. 64 bits are sufficient to represent all possible
105 : : /// values for the valid format uniquely, so there is no overflow.
106 : : ///
107 : : /// \note RFC4034 also defines the textual form of an unsigned decimal integer
108 : : /// for the corresponding time in seconds. This function doesn't support
109 : : /// this form, and if given it throws an exception of class \c InvalidTime.
110 : : ///
111 : : /// \exception InvalidTime The given textual representation is invalid.
112 : : ///
113 : : /// \param time_txt Textual time in the form of YYYYMMDDHHmmSS
114 : : /// \return Seconds since epoch corresponding to \c time_txt
115 : : uint64_t
116 : : timeFromText64(const std::string& time_txt);
117 : :
118 : : /// Convert textual DNSSEC time to integer, 32-bit version.
119 : : ///
120 : : /// This version is the same as \c timeFromText64() except that the return
121 : : /// value is wrapped around to an unsigned 32-bit integer, simply dropping
122 : : /// the upper 32 bits.
123 : : uint32_t
124 : : timeFromText32(const std::string& time_txt);
125 : :
126 : : /// Convert integral DNSSEC time to textual form, 64-bit version.
127 : : ///
128 : : /// This function takes an integer that would be seconds since epoch and
129 : : /// converts it in the form of YYYYMMDDHHmmSS. For example, if \c value is
130 : : /// 0, it returns "19700101000000". If the value corresponds to a point
131 : : /// of time on and after year 10,000, which cannot be represented in the
132 : : /// YYYY... form, an exception of class \c InvalidTime will be thrown.
133 : : ///
134 : : /// \exception InvalidTime The given time specifies on or after year 10,000.
135 : : /// \exception Other A standard exception, if resource allocation for the
136 : : /// returned text fails.
137 : : ///
138 : : /// \param value Seconds since epoch to be converted.
139 : : /// \return Textual representation of \c value in the form of YYYYMMDDHHmmSS.
140 : : std::string
141 : : timeToText64(uint64_t value);
142 : :
143 : : /// Convert integral DNSSEC time to textual form, 32-bit version.
144 : : ///
145 : : /// This version is the same as \c timeToText64(), but the time value
146 : : /// is expected to be the lower 32 bits of the full 64-bit value.
147 : : /// These two will be different on and after a certain point of time
148 : : /// in year 2106, so this function internally resolves the ambiguity
149 : : /// using the current system time at the time of function call;
150 : : /// it first identifies the range of [N*2^32 - 2^31, N*2^32 + 2^31)
151 : : /// that contains the current time, and interprets \c value in the context
152 : : /// of that range. It then applies the same process as \c timeToText64().
153 : : ///
154 : : /// There is one important exception in this processing, however.
155 : : /// Until 19 Jan 2038 03:14:08 (2^31 seconds since epoch), this range
156 : : /// would contain time before epoch. In order to ensure the returned
157 : : /// value is also a valid input to \c timeFromText, this function uses
158 : : /// a special range [0, 2^32) until that time. As a result, all upper
159 : : /// half of the 32-bit values are treated as a future time. For example,
160 : : /// 2^32-1 (the highest value in 32-bit unsigned integers) will be converted
161 : : /// to "21060207062815", instead of "19691231235959".
162 : : std::string
163 : : timeToText32(const uint32_t value);
164 : :
165 : : //@}
166 : : }
167 : : }
168 : :
169 : : #endif // __DNSSECTIME_H
170 : :
171 : : // Local Variables:
172 : : // mode: c++
173 : : // End:
|
