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>
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.
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.
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 02110-1301, USA
25
Header file for "tool" classes used in %QCA
27
These classes differ from those in qca_support.h, in that they have
28
some cryptographic relationship, and require secure memory.
30
\Note You should not use this header directly from an
31
application. You should just use <tt> \#include \<QtCrypto>
38
#include <QSharedData>
39
#include <QSharedDataPointer>
41
#include "qca_export.h"
48
Allocate a block of memory from the secure memory pool.
50
This is intended to be used when working with C libraries.
52
\param bytes the number of bytes to allocate
54
QCA_EXPORT void *qca_secure_alloc(int bytes);
57
Free (de-allocate) a block of memory that has been previously
58
allocated from the secure memory pool.
60
This is intended to be used when working with C libraries.
62
\param p pointer to the block of memory to be free'd
64
QCA_EXPORT void qca_secure_free(void *p);
67
Resize (re-allocate) a block of memory that has been previously
68
allocated from the secure memory pool.
70
\param p pointer to the block of memory to be resized.
71
\param bytes the new size that is required.
73
QCA_EXPORT void *qca_secure_realloc(void *p, int bytes);
78
\class MemoryRegion qca_tools.h QtCrypto
80
Array of bytes that may be optionally secured
82
This class is mostly unusable on its own. Either use it as a SecureArray
83
subclass or call toByteArray() to convert to QByteArray.
85
Note that this class is implicitly shared (that is, copy on write).
89
class QCA_EXPORT MemoryRegion
95
Constructs a new Memory Region from a null terminated
98
\param str pointer to the array of data to copy
100
MemoryRegion(const char *str);
103
Constructs a new MemoryRegion from the data in a
106
\param from the QByteArray to copy from
108
MemoryRegion(const QByteArray &from);
111
Standard copy constructor
113
\param from the MemoryRegion to copy from
115
MemoryRegion(const MemoryRegion &from);
119
Standard assignment operator
121
\param from the MemoryRegion to copy from
123
MemoryRegion & operator=(const MemoryRegion &from);
126
Standard assignment operator
128
\param from the QByteArray to copy from
130
MemoryRegion & operator=(const QByteArray &from);
133
Test if the MemoryRegion is null (i.e. was created
134
as a null array, and hasn't been resized).
136
This is probably not what you are trying to do. If
137
you are trying to determine whether there are any
138
bytes in the array, use isEmpty() instead.
143
Test if the MemoryRegion is using secure memory, or not.
145
In this context, memory is secure if it will not be paged
148
\return true if the memory region is secure
150
bool isSecure() const;
153
Convert this memory region to a byte array.
155
\note For secure data, this will make it insecure
157
\sa data() and constData() for other ways to convert
158
to an "accessible" format.
160
QByteArray toByteArray() const;
163
Returns true if the size of the memory region is zero.
165
bool isEmpty() const;
168
Returns the number of bytes in the memory region.
173
Convert the contents of the memory region to
174
a C-compatible character array. This consists
175
of size() bytes, followed by a null terminator.
177
\sa toByteArray for an alternative approach.
178
\sa constData, which is equivalent to this method, but avoids
179
the possibility that the compiler picks the wrong version.
181
const char *data() const;
184
Convert the contents of the memory region to
185
a C-compatible character array. This consists
186
of size() bytes, followed by a null terminator.
188
\sa toByteArray for an alternative approach.
189
\sa data which is equivalent to this method
191
const char *constData() const;
194
Obtain the value of the memory location at the specified
197
\param index the offset into the memory region.
199
\note The contents of a memory region are between
200
0 and size()-1. The content at position size() is
201
always a null terminator.
203
const char & at(int index) const;
207
Create a memory region, optionally using secure
210
\param secure if this is true, the memory region
211
will use secure storage.
213
\note This will create a memory region without
214
any content (i.e. both isNull() and isEmpty() will
217
MemoryRegion(bool secure);
220
Create a memory region, optionally using secure
223
\param size the number of bytes in the memory
225
\param secure if this is true, the memory region
226
will use secure storage.
228
MemoryRegion(int size, bool secure);
231
Create a memory region, optionally using secure
234
This constructor variant allows you to
235
initialize the memory region from an existing
238
\param from the byte array to copy from.
239
\param secure if this is true, the memory region
240
will use secure storage.
242
MemoryRegion(const QByteArray &from, bool secure);
245
Convert the contents of the memory region to
246
a C-compatible character array. This consists
247
of size() bytes, followed by a null terminator.
252
Obtain the value of the memory location at the specified
255
\param index the offset into the memory region.
257
\note The contents of a memory region are between
258
0 and size()-1. The content at position size() is
259
always a null terminator.
261
char & at(int index);
264
Resize the memory region to the specified size.
266
\param size the new size of the region.
268
bool resize(int size);
271
Modify the memory region to match a specified
272
byte array. This resizes the memory region
273
as required to match the byte array size.
275
\param from the byte array to copy from.
276
\param secure if this is true, the memory region
277
will use secure storage.
279
void set(const QByteArray &from, bool secure);
282
Convert the memory region to use the specified
285
This may involve copying data from secure to
286
insecure storage, or from insecure to secure
289
\param secure if true, use secure memory; otherwise
292
void setSecure(bool secure);
297
QSharedDataPointer<Private> d;
301
\class SecureArray qca_tools.h QtCrypto
303
Secure array of bytes
305
The %SecureArray provides an array of memory from a pool that is,
306
at least partly, secure. In this sense, secure means that the contents
307
of the memory should not be made available to other applications. By
308
comparison, a QByteArray or QString may be held in pages that might be
309
swapped to disk or free'd without being cleared first.
311
Note that this class is implicitly shared (that is, copy on write).
315
class QCA_EXPORT SecureArray : public MemoryRegion
319
Construct a secure byte array, zero length
324
Construct a secure byte array of the specified length
326
\param size the number of bytes in the array
327
\param ch the value every byte should be set to
329
explicit SecureArray(int size, char ch = 0);
332
Construct a secure byte array from a string
334
Note that this copies, rather than references the source array.
336
\param str the source of the data (as a null terminated string).
338
SecureArray(const char *str);
341
Construct a secure byte array from a QByteArray
343
Note that this copies, rather than references the source array.
345
\param a the source of the data.
349
SecureArray(const QByteArray &a);
352
Construct a secure byte array from a MemoryRegion
354
Note that this copies, rather than references the source array
356
\param a the source of the data.
360
SecureArray(const MemoryRegion &a);
363
Construct a (shallow) copy of another secure byte array
365
\param from the source of the data and length.
367
SecureArray(const SecureArray &from);
372
Creates a reference, rather than a deep copy.
374
\param from the array to reference
376
SecureArray & operator=(const SecureArray &from);
379
Creates a copy, rather than references
381
\param a the array to copy from
383
SecureArray & operator=(const QByteArray &a);
386
Clears the contents of the array and makes it empty
391
Returns a reference to the byte at the index position
393
\param index the zero-based offset to obtain
395
char & operator[](int index);
398
Returns a reference to the byte at the index position
400
\param index the zero-based offset to obtain
402
const char & operator[](int index) const;
405
Pointer to the data in the secure array
407
You can use this for memcpy and similar functions. If you are trying
408
to obtain data at a particular offset, you might be better off using
414
Pointer to the data in the secure array
416
You can use this for memcpy and similar functions. If you are trying
417
to obtain data at a particular offset, you might be better off using
420
const char *data() const;
423
Pointer to the data in the secure array
425
You can use this for memcpy and similar functions. If you are trying
426
to obtain data at a particular offset, you might be better off using
429
const char *constData() const;
432
Returns a reference to the byte at the index position
434
\param index the zero-based offset to obtain
436
char & at(int index);
439
Returns a reference to the byte at the index position
441
\param index the zero-based offset to obtain
443
const char & at(int index) const;
446
Returns the number of bytes in the array
451
Test if the array contains any bytes.
453
This is equivalent to testing (size() != 0). Note that if
454
the array is allocated, isEmpty() is false (even if no data
457
\return true if the array has zero length, otherwise false
459
bool isEmpty() const;
462
Change the length of this array
463
If the new length is less than the old length, the extra information
464
is (safely) discarded. If the new length is equal to or greater than
465
the old length, the existing data is copied into the array.
467
\param size the new length
469
bool resize(int size);
472
Fill the data array with a specified character
474
\param fillChar the character to use as the fill
475
\param fillToPosition the number of characters to fill
476
to. If not specified (or -1), fills array to
479
\note This function does not extend the array - if
480
you ask for fill beyond the current length, only
481
the current length will be used.
482
\note The number of characters is 1 based, so if
483
you ask for fill('x', 10), it will fill from
485
void fill(char fillChar, int fillToPosition = -1);
488
Copy the contents of the secure array out to a
489
standard QByteArray. Note that this performs a deep copy
492
QByteArray toByteArray() const;
495
Append a secure byte array to the end of this array
497
\param a the array to append to this array
499
SecureArray & append(const SecureArray &a);
502
Equality operator. Returns true if both arrays have the same
503
data (and the same length, of course).
505
\param other the MemoryRegion to compare to
507
bool operator==(const MemoryRegion &other) const;
510
Inequality operator. Returns true if both arrays have different
511
length, or the same length but different data.
513
\param other the MemoryRegion to compare to
515
inline bool operator!=(const MemoryRegion &other) const
517
return !(*this == other);
521
Append a secure byte array to the end of this array
523
\param a the array to append to this array
525
SecureArray & operator+=(const SecureArray &a);
529
Assign the contents of a provided byte array to this
532
\param from the byte array to copy
534
void set(const SecureArray &from);
537
Assign the contents of a provided byte array to this
540
\param from the byte array to copy
542
void set(const QByteArray &from);
546
Returns an array that is the result of concatenating a and b
548
\param a the string to put at the start of the result
549
\param b the string to put at the end of the result
551
QCA_EXPORT const SecureArray operator+(const SecureArray &a, const SecureArray &b);
554
\class BigInteger qca_tools.h QtCrypto
556
Arbitrary precision integer
558
BigInteger provides arbitrary precision integers.
560
if ( BigInteger("3499543804349") ==
561
BigInteger("38493290803248") + BigInteger( 343 ) )
569
class QCA_EXPORT BigInteger
573
Constructor. Creates a new BigInteger, initialised to zero.
580
\param n an alternative integer initialisation value.
587
\param c an alternative initialisation value, encoded as a character array
590
BigInteger b ( "9890343" );
593
BigInteger(const char *c);
598
\param s an alternative initialisation value, encoded as a string
600
BigInteger(const QString &s);
605
\param a an alternative initialisation value, encoded as SecureArray
607
BigInteger(const QCA::SecureArray &a);
612
\param from an alternative initialisation value, encoded as a %BigInteger
614
BigInteger(const BigInteger &from);
621
\param from the BigInteger to copy from
624
BigInteger a; // a is zero
626
a = b; // a is now 500
629
BigInteger & operator=(const BigInteger &from);
634
\param s the QString containing an integer representation
636
\sa bool fromString(const QString &s)
638
\note it is the application's responsibility to make sure
639
that the QString represents a valid integer (ie it only
640
contains numbers and an optional minus sign at the start)
642
BigInteger & operator=(const QString &s);
645
Increment in place operator
647
\param b the amount to increment by
650
BigInteger a; // a is zero
652
a += b; // a is now 500
653
a += b; // a is now 1000
656
BigInteger & operator+=(const BigInteger &b);
659
Decrement in place operator
661
\param b the amount to decrement by
664
BigInteger a; // a is zero
666
a -= b; // a is now -500
667
a -= b; // a is now -1000
670
BigInteger & operator-=(const BigInteger &b);
673
Multiply in place operator
675
\param b the amount to multiply by
677
BigInteger & operator*=(const BigInteger &b);
680
Divide in place operator
682
\param b the amount to divide by
684
BigInteger & operator/=(const BigInteger &b);
687
Modulo in place operator
689
\param b the amount to divide by
691
BigInteger & operator%=(const BigInteger &b);
694
Output %BigInteger as a byte array, useful for storage or
695
transmission. The format is a binary integer in sign-extended
698
\sa void fromArray(const SecureArray &a);
700
QCA::SecureArray toArray() const;
703
Assign from an array. The input is expected to be a binary integer
704
in sign-extended network-byte-order.
706
\param a a SecureArray that represents an integer
708
\sa BigInteger(const SecureArray &a);
709
\sa SecureArray toArray() const;
711
void fromArray(const QCA::SecureArray &a);
714
Convert %BigInteger to a QString
718
BigInteger aBiggishInteger( 5878990 );
719
aString = aBiggishInteger.toString(); // aString is now "5878990"
722
QString toString() const;
725
Assign from a QString
727
\param s a QString that represents an integer
729
\note it is the application's responsibility to make sure
730
that the QString represents a valid integer (ie it only
731
contains numbers and an optional minus sign at the start)
733
\sa BigInteger(const QString &s)
734
\sa BigInteger & operator=(const QString &s)
736
bool fromString(const QString &s);
739
Compare this value with another %BigInteger
741
Normally it is more readable to use one of the operator overloads,
742
so you don't need to use this method directly.
744
\param n the BigInteger to compare with
746
\return zero if the values are the same, negative if the argument
747
is less than the value of this BigInteger, and positive if the
748
argument value is greater than this BigInteger
751
BigInteger a( "400" );
752
BigInteger b( "-400" );
753
BigInteger c( " 200 " );
755
result = a.compare( b ); // return positive 400 > -400
756
result = a.compare( c ); // return positive, 400 > 200
757
result = b.compare( c ); // return negative, -400 < 200
760
int compare(const BigInteger &n) const;
763
Equality operator. Returns true if the two BigInteger values
764
are the same, including having the same sign.
766
\param other the BigInteger to compare to
768
inline bool operator==(const BigInteger &other) const
770
return (compare(other) == 0);
774
Inequality operator. Returns true if the two BigInteger values
775
are different in magnitude, sign or both.
777
\param other the BigInteger to compare to
779
inline bool operator!=(const BigInteger &other) const
781
return !(*this == other);
785
Less than or equal operator. Returns true if the BigInteger value
786
on the left hand side is equal to or less than the BigInteger
787
value on the right hand side.
789
\param other the BigInteger to compare to
791
inline bool operator<=(const BigInteger &other) const
793
return (compare(other) <= 0);
797
Greater than or equal operator. Returns true if the BigInteger
798
value on the left hand side is equal to or greater than the
799
BigInteger value on the right hand side.
801
\param other the BigInteger to compare to
803
inline bool operator>=(const BigInteger &other) const
805
return (compare(other) >= 0);
809
Less than operator. Returns true if the BigInteger value
810
on the left hand side is less than the BigInteger value
811
on the right hand side.
813
\param other the BigInteger to compare to
815
inline bool operator<(const BigInteger &other) const
817
return (compare(other) < 0);
821
Greater than operator. Returns true if the BigInteger value
822
on the left hand side is greater than the BigInteger value
823
on the right hand side.
825
\param other the BigInteger to compare to
827
inline bool operator>(const BigInteger &other) const
829
return (compare(other) > 0);
834
QSharedDataPointer<Private> d;
842
\param stream the stream to write to
843
\param b the integer to write to the stream
847
QCA_EXPORT QTextStream &operator<<(QTextStream &stream, const BigInteger &b);
added
removed
third-party/qca/qca/include/QtCrypto/qca_tools.h
