QCA

qca_tools.h
Go to the documentation of this file.
1 /*
2  * qca_tools.h - Qt Cryptographic Architecture
3  * Copyright (C) 2003-2007 Justin Karneges <[email protected]>
4  * Copyright (C) 2004,2005 Brad Hards <[email protected]>
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19  * 02110-1301 USA
20  *
21  */
22 
23 /**
24  \file qca_tools.h
25 
26  Header file for "tool" classes used in %QCA
27 
28  These classes differ from those in qca_support.h, in that they have
29  some cryptographic relationship, and require secure memory.
30 
31  \note You should not use this header directly from an
32  application. You should just use <tt> \#include <QtCrypto>
33  </tt> instead.
34 */
35 
36 #ifndef QCA_TOOLS_H
37 #define QCA_TOOLS_H
38 
39 #include "qca_export.h"
40 #include <QMetaType>
41 #include <QSharedData>
42 #include <QSharedDataPointer>
43 
44 class QString;
45 class QByteArray;
46 class QTextStream;
47 
48 /**
49  Allocate a block of memory from the secure memory pool.
50 
51  This is intended to be used when working with C libraries.
52 
53  \param bytes the number of bytes to allocate
54 */
55 QCA_EXPORT void *qca_secure_alloc(int bytes);
56 
57 /**
58  Free (de-allocate) a block of memory that has been previously
59  allocated from the secure memory pool.
60 
61  This is intended to be used when working with C libraries.
62 
63  \param p pointer to the block of memory to be free'd
64 */
65 QCA_EXPORT void qca_secure_free(void *p);
66 
67 /**
68  Resize (re-allocate) a block of memory that has been previously
69  allocated from the secure memory pool.
70 
71  \param p pointer to the block of memory to be resized.
72  \param bytes the new size that is required.
73 */
74 QCA_EXPORT void *qca_secure_realloc(void *p, int bytes);
75 
76 namespace QCA {
77 
78 /**
79  \class MemoryRegion qca_tools.h QtCrypto
80 
81  Array of bytes that may be optionally secured
82 
83  This class is mostly unusable on its own. Either use it as a SecureArray
84  subclass or call toByteArray() to convert to QByteArray.
85 
86  Note that this class is implicitly shared (that is, copy on write).
87 
88  \ingroup UserAPI
89 */
90 class QCA_EXPORT MemoryRegion
91 {
92 public:
93  MemoryRegion();
94 
95  /**
96  Constructs a new Memory Region from a null terminated
97  character array
98 
99  \param str pointer to the array of data to copy
100  */
101  MemoryRegion(const char *str);
102 
103  /**
104  Constructs a new MemoryRegion from the data in a
105  byte array
106 
107  \param from the QByteArray to copy from
108  */
109  MemoryRegion(const QByteArray &from);
110 
111  /**
112  Standard copy constructor
113 
114  \param from the MemoryRegion to copy from
115  */
116  MemoryRegion(const MemoryRegion &from);
117  ~MemoryRegion();
118 
119  /**
120  Standard assignment operator
121 
122  \param from the MemoryRegion to copy from
123  */
124  MemoryRegion &operator=(const MemoryRegion &from);
125 
126  /**
127  Standard assignment operator
128 
129  \param from the QByteArray to copy from
130  */
131  MemoryRegion &operator=(const QByteArray &from);
132 
133  /**
134  Test if the MemoryRegion is null (i.e. was created
135  as a null array, and hasn't been resized).
136 
137  This is probably not what you are trying to do. If
138  you are trying to determine whether there are any
139  bytes in the array, use isEmpty() instead.
140  */
141  bool isNull() const;
142 
143  /**
144  Test if the MemoryRegion is using secure memory, or not.
145 
146  In this context, memory is secure if it will not be paged
147  out to disk.
148 
149  \return true if the memory region is secure
150  */
151  bool isSecure() const;
152 
153  /**
154  Convert this memory region to a byte array.
155 
156  \note For secure data, this will make it insecure
157 
158  \sa data() and constData() for other ways to convert
159  to an "accessible" format.
160  */
161  QByteArray toByteArray() const;
162 
163  /**
164  Returns true if the size of the memory region is zero.
165  */
166  bool isEmpty() const;
167 
168  /**
169  Returns the number of bytes in the memory region.
170  */
171  int size() const;
172 
173  /**
174  Convert the contents of the memory region to
175  a C-compatible character array. This consists
176  of size() bytes, followed by a null terminator.
177 
178  \sa toByteArray for an alternative approach.
179  \sa constData, which is equivalent to this method, but avoids
180  the possibility that the compiler picks the wrong version.
181  */
182  const char *data() const;
183 
184  /**
185  Convert the contents of the memory region to
186  a C-compatible character array. This consists
187  of size() bytes, followed by a null terminator.
188 
189  \sa toByteArray for an alternative approach.
190  \sa data which is equivalent to this method
191  */
192  const char *constData() const;
193 
194  /**
195  Obtain the value of the memory location at the specified
196  position.
197 
198  \param index the offset into the memory region.
199 
200  \note The contents of a memory region are between
201  0 and size()-1. The content at position size() is
202  always a null terminator.
203  */
204  const char &at(int index) const;
205 
206 protected:
207  /**
208  Create a memory region, optionally using secure
209  storage.
210 
211  \param secure if this is true, the memory region
212  will use secure storage.
213 
214  \note This will create a memory region without
215  any content (i.e. both isNull() and isEmpty() will
216  return true.
217  */
218  MemoryRegion(bool secure);
219 
220  /**
221  Create a memory region, optionally using secure
222  storage.
223 
224  \param size the number of bytes in the memory
225  region.
226  \param secure if this is true, the memory region
227  will use secure storage.
228  */
229  MemoryRegion(int size, bool secure);
230 
231  /**
232  Create a memory region, optionally using secure
233  storage.
234 
235  This constructor variant allows you to
236  initialize the memory region from an existing
237  array.
238 
239  \param from the byte array to copy from.
240  \param secure if this is true, the memory region
241  will use secure storage.
242  */
243  MemoryRegion(const QByteArray &from, bool secure);
244 
245  /**
246  Convert the contents of the memory region to
247  a C-compatible character array. This consists
248  of size() bytes, followed by a null terminator.
249  */
250  char *data();
251 
252  /**
253  Obtain the value of the memory location at the specified
254  position.
255 
256  \param index the offset into the memory region.
257 
258  \note The contents of a memory region are between
259  0 and size()-1. The content at position size() is
260  always a null terminator.
261  */
262  char &at(int index);
263 
264  /**
265  Resize the memory region to the specified size.
266 
267  \param size the new size of the region.
268  */
269  bool resize(int size);
270 
271  /**
272  Modify the memory region to match a specified
273  byte array. This resizes the memory region
274  as required to match the byte array size.
275 
276  \param from the byte array to copy from.
277  \param secure if this is true, the memory region
278  will use secure storage.
279  */
280  void set(const QByteArray &from, bool secure);
281 
282  /**
283  Convert the memory region to use the specified
284  memory type.
285 
286  This may involve copying data from secure to
287  insecure storage, or from insecure to secure
288  storage.
289 
290  \param secure if true, use secure memory; otherwise
291  use insecure memory.
292  */
293  void setSecure(bool secure);
294 
295 private:
296  bool _secure;
297  class Private;
299 };
300 
301 /**
302  \class SecureArray qca_tools.h QtCrypto
303 
304  Secure array of bytes
305 
306  The %SecureArray provides an array of memory from a pool that is,
307  at least partly, secure. In this sense, secure means that the contents
308  of the memory should not be made available to other applications. By
309  comparison, a QByteArray or QString may be held in pages that might be
310  swapped to disk or free'd without being cleared first.
311 
312  Note that this class is implicitly shared (that is, copy on write).
313 
314  \ingroup UserAPI
315 */
316 class QCA_EXPORT SecureArray : public MemoryRegion
317 {
318 public:
319  /**
320  Construct a secure byte array, zero length
321  */
322  SecureArray();
323 
324  /**
325  Construct a secure byte array of the specified length
326 
327  \param size the number of bytes in the array
328  \param ch the value every byte should be set to
329  */
330  explicit SecureArray(int size, char ch = 0);
331 
332  /**
333  Construct a secure byte array from a string
334 
335  Note that this copies, rather than references the source array.
336 
337  \param str the source of the data (as a null terminated string).
338  */
339  SecureArray(const char *str);
340 
341  /**
342  Construct a secure byte array from a QByteArray
343 
344  Note that this copies, rather than references the source array.
345 
346  \param a the source of the data.
347 
348  \sa operator=()
349  */
350  SecureArray(const QByteArray &a);
351 
352  /**
353  Construct a secure byte array from a MemoryRegion
354 
355  Note that this copies, rather than references the source array
356 
357  \param a the source of the data.
358 
359  \sa operator=()
360  */
361  SecureArray(const MemoryRegion &a);
362 
363  /**
364  Construct a (shallow) copy of another secure byte array
365 
366  \param from the source of the data and length.
367  */
368  SecureArray(const SecureArray &from);
369 
370  ~SecureArray();
371 
372  /**
373  Creates a reference, rather than a deep copy.
374 
375  \param from the array to reference
376  */
377  SecureArray &operator=(const SecureArray &from);
378 
379  /**
380  Creates a copy, rather than references
381 
382  \param a the array to copy from
383  */
384  SecureArray &operator=(const QByteArray &a);
385 
386  /**
387  Clears the contents of the array and makes it empty
388  */
389  void clear();
390 
391  /**
392  Returns a reference to the byte at the index position
393 
394  \param index the zero-based offset to obtain
395  */
396  char &operator[](int index);
397 
398  /**
399  Returns a reference to the byte at the index position
400 
401  \param index the zero-based offset to obtain
402  */
403  const char &operator[](int index) const;
404 
405  /**
406  Pointer to the data in the secure array
407 
408  You can use this for memcpy and similar functions. If you are trying
409  to obtain data at a particular offset, you might be better off using
410  at() or operator[]
411  */
412  char *data();
413 
414  /**
415  Pointer to the data in the secure array
416 
417  You can use this for memcpy and similar functions. If you are trying
418  to obtain data at a particular offset, you might be better off using
419  at() or operator[]
420  */
421  const char *data() const;
422 
423  /**
424  Pointer to the data in the secure array
425 
426  You can use this for memcpy and similar functions. If you are trying
427  to obtain data at a particular offset, you might be better off using
428  at() or operator[]
429  */
430  const char *constData() const;
431 
432  /**
433  Returns a reference to the byte at the index position
434 
435  \param index the zero-based offset to obtain
436  */
437  char &at(int index);
438 
439  /**
440  Returns a reference to the byte at the index position
441 
442  \param index the zero-based offset to obtain
443  */
444  const char &at(int index) const;
445 
446  /**
447  Returns the number of bytes in the array
448  */
449  int size() const;
450 
451  /**
452  Test if the array contains any bytes.
453 
454  This is equivalent to testing (size() != 0). Note that if
455  the array is allocated, isEmpty() is false (even if no data
456  has been added)
457 
458  \return true if the array has zero length, otherwise false
459  */
460  bool isEmpty() const;
461 
462  /**
463  Change the length of this array
464  If the new length is less than the old length, the extra information
465  is (safely) discarded. If the new length is equal to or greater than
466  the old length, the existing data is copied into the array.
467 
468  \param size the new length
469  */
470  bool resize(int size);
471 
472  /**
473  Fill the data array with a specified character
474 
475  \param fillChar the character to use as the fill
476  \param fillToPosition the number of characters to fill
477  to. If not specified (or -1), fills array to
478  current length.
479 
480  \note This function does not extend the array - if
481  you ask for fill beyond the current length, only
482  the current length will be used.
483  \note The number of characters is 1 based, so if
484  you ask for fill('x', 10), it will fill from
485  */
486  void fill(char fillChar, int fillToPosition = -1);
487 
488  /**
489  Copy the contents of the secure array out to a
490  standard QByteArray. Note that this performs a deep copy
491  of the data.
492  */
493  QByteArray toByteArray() const;
494 
495  /**
496  Append a secure byte array to the end of this array
497 
498  \param a the array to append to this array
499  */
500  SecureArray &append(const SecureArray &a);
501 
502  /**
503  Equality operator. Returns true if both arrays have the same
504  data (and the same length, of course).
505 
506  \param other the MemoryRegion to compare to
507  */
508  bool operator==(const MemoryRegion &other) const;
509 
510  /**
511  Inequality operator. Returns true if both arrays have different
512  length, or the same length but different data.
513 
514  \param other the MemoryRegion to compare to
515  */
516  inline bool operator!=(const MemoryRegion &other) const
517  {
518  return !(*this == other);
519  }
520 
521  /**
522  Append a secure byte array to the end of this array
523 
524  \param a the array to append to this array
525  */
526  SecureArray &operator+=(const SecureArray &a);
527 
528 protected:
529  /**
530  Assign the contents of a provided byte array to this
531  object.
532 
533  \param from the byte array to copy
534  */
535  void set(const SecureArray &from);
536 
537  /**
538  Assign the contents of a provided byte array to this
539  object.
540 
541  \param from the byte array to copy
542  */
543  void set(const QByteArray &from);
544 };
545 
546 /**
547  Returns an array that is the result of concatenating a and b
548 
549  \param a the string to put at the start of the result
550  \param b the string to put at the end of the result
551 */
552 QCA_EXPORT const SecureArray operator+(const SecureArray &a, const SecureArray &b);
553 
554 /**
555  \class BigInteger qca_tools.h QtCrypto
556 
557  Arbitrary precision integer
558 
559  BigInteger provides arbitrary precision integers.
560  \code
561 if ( BigInteger("3499543804349") ==
562  BigInteger("38493290803248") + BigInteger( 343 ) )
563 {
564  // do something
565 }
566  \endcode
567 
568  \ingroup UserAPI
569 */
570 class QCA_EXPORT BigInteger
571 {
572 public:
573  /**
574  Constructor. Creates a new BigInteger, initialised to zero.
575  */
576  BigInteger();
577 
578  /**
579  \overload
580 
581  \param n an alternative integer initialisation value.
582  */
583  BigInteger(int n);
584 
585  /**
586  \overload
587 
588  \param c an alternative initialisation value, encoded as a character array
589 
590  \code
591 BigInteger b ( "9890343" );
592  \endcode
593  */
594  BigInteger(const char *c);
595 
596  /**
597  \overload
598 
599  \param s an alternative initialisation value, encoded as a string
600  */
601  BigInteger(const QString &s);
602 
603  /**
604  \overload
605 
606  \param a an alternative initialisation value, encoded as SecureArray
607  */
608  BigInteger(const QCA::SecureArray &a);
609 
610  /**
611  \overload
612 
613  \param from an alternative initialisation value, encoded as a %BigInteger
614  */
615  BigInteger(const BigInteger &from);
616 
617  ~BigInteger();
618 
619  /**
620  Assignment operator
621 
622  \param from the BigInteger to copy from
623 
624  \code
625 BigInteger a; // a is zero
626 BigInteger b( 500 );
627 a = b; // a is now 500
628  \endcode
629  */
630  BigInteger &operator=(const BigInteger &from);
631 
632  /**
633  \overload
634 
635  \param s the QString containing an integer representation
636 
637  \sa bool fromString(const QString &s)
638 
639  \note it is the application's responsibility to make sure
640  that the QString represents a valid integer (ie it only
641  contains numbers and an optional minus sign at the start)
642  */
643  BigInteger &operator=(const QString &s);
644 
645  /**
646  Increment in place operator
647 
648  \param b the amount to increment by
649 
650  \code
651 BigInteger a; // a is zero
652 BigInteger b( 500 );
653 a += b; // a is now 500
654 a += b; // a is now 1000
655  \endcode
656  */
657  BigInteger &operator+=(const BigInteger &b);
658 
659  /**
660  Decrement in place operator
661 
662  \param b the amount to decrement by
663 
664  \code
665 BigInteger a; // a is zero
666 BigInteger b( 500 );
667 a -= b; // a is now -500
668 a -= b; // a is now -1000
669  \endcode
670  */
671  BigInteger &operator-=(const BigInteger &b);
672 
673  /**
674  Multiply in place operator
675 
676  \param b the amount to multiply by
677  */
678  BigInteger &operator*=(const BigInteger &b);
679 
680  /**
681  Divide in place operator
682 
683  \param b the amount to divide by
684  */
685  BigInteger &operator/=(const BigInteger &b);
686 
687  /**
688  Modulo in place operator
689 
690  \param b the amount to divide by
691  */
692  BigInteger &operator%=(const BigInteger &b);
693 
694  /**
695  Output %BigInteger as a byte array, useful for storage or
696  transmission. The format is a binary integer in sign-extended
697  network-byte-order.
698 
699  \sa void fromArray(const SecureArray &a);
700  */
701  QCA::SecureArray toArray() const;
702 
703  /**
704  Assign from an array. The input is expected to be a binary integer
705  in sign-extended network-byte-order.
706 
707  \param a a SecureArray that represents an integer
708 
709  \sa BigInteger(const SecureArray &a);
710  \sa SecureArray toArray() const;
711  */
712  void fromArray(const QCA::SecureArray &a);
713 
714  /**
715  Convert %BigInteger to a QString
716 
717  \code
718 QString aString;
719 BigInteger aBiggishInteger( 5878990 );
720 aString = aBiggishInteger.toString(); // aString is now "5878990"
721  \endcode
722  */
723  QString toString() const;
724 
725  /**
726  Assign from a QString
727 
728  \param s a QString that represents an integer
729 
730  \note it is the application's responsibility to make sure
731  that the QString represents a valid integer (ie it only
732  contains numbers and an optional minus sign at the start)
733 
734  \sa BigInteger(const QString &s)
735  \sa BigInteger & operator=(const QString &s)
736  */
737  bool fromString(const QString &s);
738 
739  /**
740  Compare this value with another %BigInteger
741 
742  Normally it is more readable to use one of the operator overloads,
743  so you don't need to use this method directly.
744 
745  \param n the BigInteger to compare with
746 
747  \return zero if the values are the same, negative if the argument
748  is less than the value of this BigInteger, and positive if the
749  argument value is greater than this BigInteger
750 
751  \code
752 BigInteger a( "400" );
753 BigInteger b( "-400" );
754 BigInteger c( " 200 " );
755 int result;
756 result = a.compare( b ); // return positive 400 > -400
757 result = a.compare( c ); // return positive, 400 > 200
758 result = b.compare( c ); // return negative, -400 < 200
759  \endcode
760  */
761  int compare(const BigInteger &n) const;
762 
763  /**
764  Equality operator. Returns true if the two BigInteger values
765  are the same, including having the same sign.
766 
767  \param other the BigInteger to compare to
768  */
769  inline bool operator==(const BigInteger &other) const
770  {
771  return (compare(other) == 0);
772  }
773 
774  /**
775  Inequality operator. Returns true if the two BigInteger values
776  are different in magnitude, sign or both.
777 
778  \param other the BigInteger to compare to
779  */
780  inline bool operator!=(const BigInteger &other) const
781  {
782  return !(*this == other);
783  }
784 
785  /**
786  Less than or equal operator. Returns true if the BigInteger value
787  on the left hand side is equal to or less than the BigInteger
788  value on the right hand side.
789 
790  \param other the BigInteger to compare to
791  */
792  inline bool operator<=(const BigInteger &other) const
793  {
794  return (compare(other) <= 0);
795  }
796 
797  /**
798  Greater than or equal operator. Returns true if the BigInteger
799  value on the left hand side is equal to or greater than the
800  BigInteger value on the right hand side.
801 
802  \param other the BigInteger to compare to
803  */
804  inline bool operator>=(const BigInteger &other) const
805  {
806  return (compare(other) >= 0);
807  }
808 
809  /**
810  Less than operator. Returns true if the BigInteger value
811  on the left hand side is less than the BigInteger value
812  on the right hand side.
813 
814  \param other the BigInteger to compare to
815  */
816  inline bool operator<(const BigInteger &other) const
817  {
818  return (compare(other) < 0);
819  }
820 
821  /**
822  Greater than operator. Returns true if the BigInteger value
823  on the left hand side is greater than the BigInteger value
824  on the right hand side.
825 
826  \param other the BigInteger to compare to
827  */
828  inline bool operator>(const BigInteger &other) const
829  {
830  return (compare(other) > 0);
831  }
832 
833 private:
834  class Private;
836 };
837 
838 /**
839  Stream operator
840 
841  \param stream the stream to write to
842  \param b the integer to write to the stream
843 
844  \relates BigInteger
845 */
846 QCA_EXPORT QTextStream &operator<<(QTextStream &stream, const BigInteger &b);
847 
848 }
849 
850 #endif
bool operator>=(const BigInteger &other) const
Greater than or equal operator.
Definition: qca_tools.h:804
bool operator!=(const MemoryRegion &other) const
Inequality operator.
Definition: qca_tools.h:516
bool operator==(const BigInteger &other) const
Equality operator.
Definition: qca_tools.h:769
QCA_EXPORT void * qca_secure_alloc(int bytes)
Allocate a block of memory from the secure memory pool.
bool operator<=(const BigInteger &other) const
Less than or equal operator.
Definition: qca_tools.h:792
bool operator>(const BigInteger &other) const
Greater than operator.
Definition: qca_tools.h:828
bool operator<(const BigInteger &other) const
Less than operator.
Definition: qca_tools.h:816
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:41
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
QCA_EXPORT void * qca_secure_realloc(void *p, int bytes)
Resize (re-allocate) a block of memory that has been previously allocated from the secure memory pool...
QCA_EXPORT void qca_secure_free(void *p)
Free (de-allocate) a block of memory that has been previously allocated from the secure memory pool.
const QCA_EXPORT SecureArray operator+(const SecureArray &a, const SecureArray &b)
Returns an array that is the result of concatenating a and b.
bool operator!=(const BigInteger &other) const
Inequality operator.
Definition: qca_tools.h:780
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 03:50:44 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.