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