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