Crypto++ 8.2
Free C&
simple.h
Go to the documentation of this file.
1// simple.h - originally written and placed in the public domain by Wei Dai
2
3/// \file simple.h
4/// \brief Classes providing basic library services.
5
6#ifndef CRYPTOPP_SIMPLE_H
7#define CRYPTOPP_SIMPLE_H
8
9#include "config.h"
10
11#if CRYPTOPP_MSC_VERSION
12# pragma warning(push)
13# pragma warning(disable: 4127 4189)
14#endif
15
16#include "cryptlib.h"
17#include "misc.h"
18
19NAMESPACE_BEGIN(CryptoPP)
20
21/// \brief Base class for identifying alogorithm
22/// \tparam BASE base class from which to derive
23/// \tparam DERIVED class which to clone
24template <class DERIVED, class BASE>
25class CRYPTOPP_NO_VTABLE ClonableImpl : public BASE
26{
27public:
28 Clonable * Clone() const {return new DERIVED(*static_cast<const DERIVED *>(this));}
29};
30
31/// \brief Base class information
32/// \tparam BASE an Algorithm derived class
33/// \tparam ALGORITHM_INFO an Algorithm derived class
34/// \details AlgorithmImpl provides StaticAlgorithmName from the template parameter BASE
35template <class BASE, class ALGORITHM_INFO=BASE>
36class CRYPTOPP_NO_VTABLE AlgorithmImpl : public BASE
37{
38public:
39 /// \brief The algorithm name
40 /// \returns the algorithm name
41 /// \details StaticAlgorithmName returns the algorithm's name as a static member function.
42 /// The name is taken from information provided by BASE.
43 static std::string CRYPTOPP_API StaticAlgorithmName() {return ALGORITHM_INFO::StaticAlgorithmName();}
44 /// \brief The algorithm name
45 /// \returns the algorithm name
46 /// \details AlgorithmName returns the algorithm's name as a member function.
47 /// The name is is acquired by calling StaticAlgorithmName.
48 std::string AlgorithmName() const {return ALGORITHM_INFO::StaticAlgorithmName();}
49};
50
51/// \brief Exception thrown when an invalid key length is encountered
52class CRYPTOPP_DLL InvalidKeyLength : public InvalidArgument
53{
54public:
55 explicit InvalidKeyLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid key length") {}
56};
57
58/// \brief Exception thrown when an invalid number of rounds is encountered
59class CRYPTOPP_DLL InvalidRounds : public InvalidArgument
60{
61public:
62 explicit InvalidRounds(const std::string &algorithm, unsigned int rounds) : InvalidArgument(algorithm + ": " + IntToString(rounds) + " is not a valid number of rounds") {}
63};
64
65/// \brief Exception thrown when an invalid block size is encountered
66class CRYPTOPP_DLL InvalidBlockSize : public InvalidArgument
67{
68public:
69 explicit InvalidBlockSize(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid block size") {}
70};
71
72/// \brief Exception thrown when an invalid derived key length is encountered
73class CRYPTOPP_DLL InvalidDerivedLength : public InvalidArgument
74{
75public:
76 explicit InvalidDerivedLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid derived key length") {}
77};
78
79/// \brief Exception thrown when an invalid personalization string length is encountered
81{
82public:
83 explicit InvalidPersonalizationLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {}
84};
85
86/// \brief Exception thrown when an invalid salt length is encountered
87class CRYPTOPP_DLL InvalidSaltLength : public InvalidArgument
88{
89public:
90 explicit InvalidSaltLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {}
91};
92
93// *****************************
94
95/// \brief Base class for bufferless filters
96/// \tparam T the class or type
97template <class T>
98class CRYPTOPP_NO_VTABLE Bufferless : public T
99{
100public:
101 bool IsolatedFlush(bool hardFlush, bool blocking)
102 {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); return false;}
103};
104
105/// \brief Base class for unflushable filters
106/// \tparam T the class or type
107template <class T>
108class CRYPTOPP_NO_VTABLE Unflushable : public T
109{
110public:
111 bool Flush(bool completeFlush, int propagation=-1, bool blocking=true)
112 {return ChannelFlush(DEFAULT_CHANNEL, completeFlush, propagation, blocking);}
113 bool IsolatedFlush(bool hardFlush, bool blocking)
114 {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); CRYPTOPP_ASSERT(false); return false;}
115 bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true)
116 {
117 if (hardFlush && !InputBufferIsEmpty())
118 throw CannotFlush("Unflushable<T>: this object has buffered input that cannot be flushed");
119 else
120 {
121 BufferedTransformation *attached = this->AttachedTransformation();
122 return attached && propagation ? attached->ChannelFlush(channel, hardFlush, propagation-1, blocking) : false;
123 }
124 }
125
126protected:
127 virtual bool InputBufferIsEmpty() const {return false;}
128};
129
130/// \brief Base class for input rejecting filters
131/// \tparam T the class or type
132/// \details T should be a BufferedTransformation derived class
133template <class T>
134class CRYPTOPP_NO_VTABLE InputRejecting : public T
135{
136public:
138 {InputRejected() : NotImplemented("BufferedTransformation: this object doesn't allow input") {}};
139
140 /// \name INPUT
141 //@{
142
143 /// \brief Input a byte array for processing
144 /// \param inString the byte array to process
145 /// \param length the size of the string, in bytes
146 /// \param messageEnd means how many filters to signal MessageEnd() to, including this one
147 /// \param blocking specifies whether the object should block when processing input
148 /// \throws InputRejected
149 /// \returns the number of bytes that remain in the block (i.e., bytes not processed)
150 /// \details Internally, the default implementation throws InputRejected.
151 size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking)
152 {CRYPTOPP_UNUSED(inString); CRYPTOPP_UNUSED(length); CRYPTOPP_UNUSED(messageEnd); CRYPTOPP_UNUSED(blocking); throw InputRejected();}
153 //@}
154
155 /// \name SIGNALS
156 //@{
157 bool IsolatedFlush(bool hardFlush, bool blocking)
158 {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); return false;}
159 bool IsolatedMessageSeriesEnd(bool blocking)
160 {CRYPTOPP_UNUSED(blocking); throw InputRejected();}
161 size_t ChannelPut2(const std::string &channel, const byte *inString, size_t length, int messageEnd, bool blocking)
162 {CRYPTOPP_UNUSED(channel); CRYPTOPP_UNUSED(inString); CRYPTOPP_UNUSED(length); CRYPTOPP_UNUSED(messageEnd); CRYPTOPP_UNUSED(blocking); throw InputRejected();}
163 bool ChannelMessageSeriesEnd(const std::string& channel, int messageEnd, bool blocking)
164 {CRYPTOPP_UNUSED(channel); CRYPTOPP_UNUSED(messageEnd); CRYPTOPP_UNUSED(blocking); throw InputRejected();}
165 //@}
166};
167
168/// \brief Interface for custom flush signals propagation
169/// \tparam T BufferedTransformation derived class
170template <class T>
171class CRYPTOPP_NO_VTABLE CustomFlushPropagation : public T
172{
173public:
174 /// \name SIGNALS
175 //@{
176
177 /// \brief Flush buffered input and/or output, with signal propagation
178 /// \param hardFlush is used to indicate whether all data should be flushed
179 /// \param propagation the number of attached transformations the Flush() signal should be passed
180 /// \param blocking specifies whether the object should block when processing input
181 /// \details propagation count includes this object. Setting propagation to <tt>1</tt> means this
182 /// object only. Setting propagation to <tt>-1</tt> means unlimited propagation.
183 /// \note Hard flushes must be used with care. It means try to process and output everything, even if
184 /// there may not be enough data to complete the action. For example, hard flushing a HexDecoder
185 /// would cause an error if you do it after inputing an odd number of hex encoded characters.
186 /// \note For some types of filters, like ZlibDecompressor, hard flushes can only
187 /// be done at "synchronization points". These synchronization points are positions in the data
188 /// stream that are created by hard flushes on the corresponding reverse filters, in this
189 /// example ZlibCompressor. This is useful when zlib compressed data is moved across a
190 /// network in packets and compression state is preserved across packets, as in the SSH2 protocol.
191 virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true) =0;
192
193 //@}
194
195private:
196 bool IsolatedFlush(bool hardFlush, bool blocking)
197 {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); CRYPTOPP_ASSERT(false); return false;}
198};
199
200/// \brief Interface for custom flush signals
201/// \tparam T BufferedTransformation derived class
202template <class T>
203class CRYPTOPP_NO_VTABLE CustomSignalPropagation : public CustomFlushPropagation<T>
204{
205public:
206 /// \brief Initialize or reinitialize this object, with signal propagation
207 /// \param parameters a set of NameValuePairs to initialize or reinitialize this object
208 /// \param propagation the number of attached transformations the Initialize() signal should be passed
209 /// \details Initialize() is used to initialize or reinitialize an object using a variable number of
210 /// arbitrarily typed arguments. The function avoids the need for multiple constructors providing
211 /// all possible combintations of configurable parameters.
212 /// \details propagation count includes this object. Setting propagation to <tt>1</tt> means this
213 /// object only. Setting propagation to <tt>-1</tt> means unlimited propagation.
214 virtual void Initialize(const NameValuePairs &parameters=g_nullNameValuePairs, int propagation=-1) =0;
215
216private:
217 void IsolatedInitialize(const NameValuePairs &parameters)
218 {CRYPTOPP_UNUSED(parameters); CRYPTOPP_ASSERT(false);}
219};
220
221/// \brief Multiple channels support for custom signal processing
222/// \tparam T the class or type
223/// \details T should be a BufferedTransformation derived class
224template <class T>
225class CRYPTOPP_NO_VTABLE Multichannel : public CustomFlushPropagation<T>
226{
227public:
228 bool Flush(bool hardFlush, int propagation=-1, bool blocking=true)
229 {return this->ChannelFlush(DEFAULT_CHANNEL, hardFlush, propagation, blocking);}
230
231 /// \brief Marks the end of a series of messages, with signal propagation
232 /// \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed
233 /// \param blocking specifies whether the object should block when processing input
234 /// \details Each object that receives the signal will perform its processing, decrement
235 /// propagation, and then pass the signal on to attached transformations if the value is not 0.
236 /// \details propagation count includes this object. Setting propagation to <tt>1</tt> means this
237 /// object only. Setting propagation to <tt>-1</tt> means unlimited propagation.
238 /// \note There should be a MessageEnd() immediately before MessageSeriesEnd().
239 bool MessageSeriesEnd(int propagation=-1, bool blocking=true)
240 {return this->ChannelMessageSeriesEnd(DEFAULT_CHANNEL, propagation, blocking);}
241
242 /// \brief Request space which can be written into by the caller
243 /// \param size the requested size of the buffer
244 /// \details The purpose of this method is to help avoid extra memory allocations.
245 /// \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made,
246 /// size is the requested size of the buffer. When the call returns, size is the size of
247 /// the array returned to the caller.
248 /// \details The base class implementation sets size to 0 and returns NULL.
249 /// \note Some objects, like ArraySink, cannot create a space because its fixed. In the case of
250 /// an ArraySink, the pointer to the array is returned and the size is remaining size.
251 byte * CreatePutSpace(size_t &size)
252 {return this->ChannelCreatePutSpace(DEFAULT_CHANNEL, size);}
253
254 /// \brief Input multiple bytes for processing
255 /// \param inString the byte buffer to process
256 /// \param length the size of the string, in bytes
257 /// \param messageEnd means how many filters to signal MessageEnd() to, including this one
258 /// \param blocking specifies whether the object should block when processing input
259 /// \details Derived classes must implement Put2().
260 size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking)
261 {return this->ChannelPut2(DEFAULT_CHANNEL, inString, length, messageEnd, blocking);}
262
263 /// \brief Input multiple bytes that may be modified by callee.
264 /// \param inString the byte buffer to process.
265 /// \param length the size of the string, in bytes.
266 /// \param messageEnd means how many filters to signal MessageEnd() to, including this one.
267 /// \param blocking specifies whether the object should block when processing input.
268 /// \details Internally, PutModifiable2() calls Put2().
269 size_t PutModifiable2(byte *inString, size_t length, int messageEnd, bool blocking)
270 {return this->ChannelPutModifiable2(DEFAULT_CHANNEL, inString, length, messageEnd, blocking);}
271
272// void ChannelMessageSeriesEnd(const std::string &channel, int propagation=-1)
273// {PropagateMessageSeriesEnd(propagation, channel);}
274 byte * ChannelCreatePutSpace(const std::string &channel, size_t &size)
275 {CRYPTOPP_UNUSED(channel); size = 0; return NULLPTR;}
276 bool ChannelPutModifiable(const std::string &channel, byte *inString, size_t length)
277 {this->ChannelPut(channel, inString, length); return false;}
278
279 virtual size_t ChannelPut2(const std::string &channel, const byte *begin, size_t length, int messageEnd, bool blocking) =0;
280 size_t ChannelPutModifiable2(const std::string &channel, byte *begin, size_t length, int messageEnd, bool blocking)
281 {return ChannelPut2(channel, begin, length, messageEnd, blocking);}
282
283 virtual bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true) =0;
284};
285
286/// \brief Provides auto signaling support
287/// \tparam T BufferedTransformation derived class
288template <class T>
289class CRYPTOPP_NO_VTABLE AutoSignaling : public T
290{
291public:
292 /// \brief Construct an AutoSignaling
293 /// \param propagation the propagation count
294 AutoSignaling(int propagation=-1) : m_autoSignalPropagation(propagation) {}
295
296 void SetAutoSignalPropagation(int propagation)
297 {m_autoSignalPropagation = propagation;}
298 int GetAutoSignalPropagation() const
299 {return m_autoSignalPropagation;}
300
301private:
302 int m_autoSignalPropagation;
303};
304
305/// \brief Acts as a Source for pre-existing, static data
306class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Store : public AutoSignaling<InputRejecting<BufferedTransformation> >
307{
308public:
309 /// \brief Construct a Store
310 Store() : m_messageEnd(false) {}
311
312 void IsolatedInitialize(const NameValuePairs &parameters)
313 {
314 m_messageEnd = false;
315 StoreInitialize(parameters);
316 }
317
318 unsigned int NumberOfMessages() const {return m_messageEnd ? 0 : 1;}
319 bool GetNextMessage();
320 unsigned int CopyMessagesTo(BufferedTransformation &target, unsigned int count=UINT_MAX, const std::string &channel=DEFAULT_CHANNEL) const;
321
322protected:
323 virtual void StoreInitialize(const NameValuePairs &parameters) =0;
324
325 bool m_messageEnd;
326};
327
328/// \brief Implementation of BufferedTransformation's attachment interface
329/// \details Sink is a cornerstone of the Pipeline trinitiy. Data flows from
330/// Sources, through Filters, and then terminates in Sinks. The difference
331/// between a Source and Filter is a Source \a pumps data, while a Filter does
332/// not. The difference between a Filter and a Sink is a Filter allows an
333/// attached transformation, while a Sink does not.
334/// \details A Sink doesnot produce any retrievable output.
335/// \details See the discussion of BufferedTransformation in cryptlib.h for
336/// more details.
337class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Sink : public BufferedTransformation
338{
339public:
340 size_t TransferTo2(BufferedTransformation &target, lword &transferBytes, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true)
341 {CRYPTOPP_UNUSED(target); CRYPTOPP_UNUSED(transferBytes); CRYPTOPP_UNUSED(channel); CRYPTOPP_UNUSED(blocking); transferBytes = 0; return 0;}
342 size_t CopyRangeTo2(BufferedTransformation &target, lword &begin, lword end=LWORD_MAX, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true) const
343 {CRYPTOPP_UNUSED(target); CRYPTOPP_UNUSED(begin); CRYPTOPP_UNUSED(end); CRYPTOPP_UNUSED(channel); CRYPTOPP_UNUSED(blocking); return 0;}
344};
345
346/// \brief Acts as an input discarding Filter or Sink
347/// \details The BitBucket discards all input and returns 0 to the caller
348/// to indicate all data was processed.
349class CRYPTOPP_DLL BitBucket : public Bufferless<Sink>
350{
351public:
352 std::string AlgorithmName() const {return "BitBucket";}
354 {CRYPTOPP_UNUSED(params);}
355 size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking)
356 {CRYPTOPP_UNUSED(inString); CRYPTOPP_UNUSED(length); CRYPTOPP_UNUSED(messageEnd); CRYPTOPP_UNUSED(blocking); return 0;}
357};
358
359NAMESPACE_END
360
361#if CRYPTOPP_MSC_VERSION
362# pragma warning(pop)
363#endif
364
365#endif
Base class information.
Definition: simple.h:37
static std::string StaticAlgorithmName()
The algorithm name.
Definition: simple.h:43
std::string AlgorithmName() const
The algorithm name.
Definition: simple.h:48
Provides auto signaling support.
Definition: simple.h:290
AutoSignaling(int propagation=-1)
Construct an AutoSignaling.
Definition: simple.h:294
Acts as an input discarding Filter or Sink.
Definition: simple.h:350
size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking)
Input multiple bytes for processing.
Definition: simple.h:355
void IsolatedInitialize(const NameValuePairs &params)
Initialize or reinitialize this object, without signal propagation.
Definition: simple.h:353
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: simple.h:352
Interface for buffered transformations.
Definition: cryptlib.h:1599
virtual bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true)
Flush buffered input and/or output on a channel.
Definition: cryptlib.cpp:484
Base class for bufferless filters.
Definition: simple.h:99
Flush(true) was called but it can't completely flush its buffers.
Definition: cryptlib.h:231
Interface for cloning objects.
Definition: cryptlib.h:557
Base class for identifying alogorithm.
Definition: simple.h:26
Interface for custom flush signals propagation.
Definition: simple.h:172
virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true)=0
Flush buffered input and/or output, with signal propagation.
Interface for custom flush signals.
Definition: simple.h:204
virtual void Initialize(const NameValuePairs &parameters=g_nullNameValuePairs, int propagation=-1)=0
Initialize or reinitialize this object, with signal propagation.
Base class for input rejecting filters.
Definition: simple.h:135
size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking)
Input a byte array for processing.
Definition: simple.h:151
An invalid argument was detected.
Definition: cryptlib.h:203
Exception thrown when an invalid block size is encountered.
Definition: simple.h:67
Exception thrown when an invalid derived key length is encountered.
Definition: simple.h:74
Exception thrown when an invalid key length is encountered.
Definition: simple.h:53
Exception thrown when an invalid personalization string length is encountered.
Definition: simple.h:81
Exception thrown when an invalid number of rounds is encountered.
Definition: simple.h:60
Exception thrown when an invalid salt length is encountered.
Definition: simple.h:88
Multiple channels support for custom signal processing.
Definition: simple.h:226
byte * CreatePutSpace(size_t &size)
Request space which can be written into by the caller.
Definition: simple.h:251
bool MessageSeriesEnd(int propagation=-1, bool blocking=true)
Marks the end of a series of messages, with signal propagation.
Definition: simple.h:239
size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking)
Input multiple bytes for processing.
Definition: simple.h:260
bool Flush(bool hardFlush, int propagation=-1, bool blocking=true)
Flush buffered input and/or output, with signal propagation.
Definition: simple.h:228
size_t PutModifiable2(byte *inString, size_t length, int messageEnd, bool blocking)
Input multiple bytes that may be modified by callee.
Definition: simple.h:269
Interface for retrieving values given their names.
Definition: cryptlib.h:294
A method was called which was not implemented.
Definition: cryptlib.h:224
Implementation of BufferedTransformation's attachment interface.
Definition: simple.h:338
size_t TransferTo2(BufferedTransformation &target, lword &transferBytes, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true)
Transfer bytes from this object to another BufferedTransformation.
Definition: simple.h:340
size_t CopyRangeTo2(BufferedTransformation &target, lword &begin, lword end=LWORD_MAX, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true) const
Copy bytes from this object to another BufferedTransformation.
Definition: simple.h:342
Acts as a Source for pre-existing, static data.
Definition: simple.h:307
void IsolatedInitialize(const NameValuePairs &parameters)
Initialize or reinitialize this object, without signal propagation.
Definition: simple.h:312
Store()
Construct a Store.
Definition: simple.h:310
unsigned int NumberOfMessages() const
Provides the number of meesages processed by this object.
Definition: simple.h:318
Base class for unflushable filters.
Definition: simple.h:109
Library configuration file.
Abstract base classes that provide a uniform interface to this library.
Utility functions for the Crypto++ library.
std::string IntToString(T value, unsigned int base=10)
Converts a value to a string.
Definition: misc.h:636
Crypto++ library namespace.
#define CRYPTOPP_ASSERT(exp)
Debugging and diagnostic assertion.
Definition: trap.h:69