1/*
2 * qca_tools.h - Qt Cryptographic Architecture
3 * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com>
4 * Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net>
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
44class QString;
45class QByteArray;
46class 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*/
55QCA_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*/
65QCA_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*/
74QCA_EXPORT void *qca_secure_realloc(void *p, int bytes);
75
76namespace 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*/
90class QCA_EXPORT MemoryRegion
91{
92public:
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
206protected:
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
295private:
296 bool _secure;
297 class Private;
298 QSharedDataPointer<Private> d;
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*/
316class QCA_EXPORT SecureArray : public MemoryRegion
317{
318public:
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
528protected:
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*/
552QCA_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
561if ( BigInteger("3499543804349") ==
562 BigInteger("38493290803248") + BigInteger( 343 ) )
563{
564 // do something
565}
566 \endcode
567
568 \ingroup UserAPI
569*/
570class QCA_EXPORT BigInteger
571{
572public:
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
591BigInteger 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
625BigInteger a; // a is zero
626BigInteger b( 500 );
627a = 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
651BigInteger a; // a is zero
652BigInteger b( 500 );
653a += b; // a is now 500
654a += 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
665BigInteger a; // a is zero
666BigInteger b( 500 );
667a -= b; // a is now -500
668a -= 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
718QString aString;
719BigInteger aBiggishInteger( 5878990 );
720aString = 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
752BigInteger a( "400" );
753BigInteger b( "-400" );
754BigInteger c( " 200 " );
755int result;
756result = a.compare( b ); // return positive 400 > -400
757result = a.compare( c ); // return positive, 400 > 200
758result = 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(n: 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(n: 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(n: 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(n: 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(n: other) > 0);
831 }
832
833private:
834 class Private;
835 QSharedDataPointer<Private> d;
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*/
846QCA_EXPORT QTextStream &operator<<(QTextStream &stream, const BigInteger &b);
847
848}
849
850#endif
851

source code of qca/include/QtCrypto/qca_tools.h