File indexing completed on 2024-04-28 04:43:41

 /*
  * qca_tools.h - Qt Cryptographic Architecture
  * Copyright (C) 2003-2007  Justin Karneges <justin@affinix.com>
  * Copyright (C) 2004,2005  Brad Hards <bradh@frogmouth.net>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  * 02110-1301  USA
  *
  */
 
 /**
    \file qca_tools.h
 
    Header file for "tool" classes used in %QCA
 
    These classes differ from those in qca_support.h, in that they have
    some cryptographic relationship, and require secure memory.
 
    \note You should not use this header directly from an
    application. You should just use <tt> \#include \<QtCrypto>
    </tt> instead.
 */
 
 #ifndef QCA_TOOLS_H
 #define QCA_TOOLS_H
 
 #include "qca_export.h"
 #include <QMetaType>
 #include <QSharedData>
 #include <QSharedDataPointer>
 
 class QString;
 class QByteArray;
 class QTextStream;
 
 /**
    Allocate a block of memory from the secure memory pool.
 
    This is intended to be used when working with C libraries.
 
    \param bytes the number of bytes to allocate
 */
 QCA_EXPORT void *qca_secure_alloc(int bytes);
 
 /**
    Free (de-allocate) a block of memory that has been previously
    allocated from the secure memory pool.
 
    This is intended to be used when working with C libraries.
 
    \param p pointer to the block of memory to be free'd
 */
 QCA_EXPORT void qca_secure_free(void *p);
 
 /**
    Resize (re-allocate) a block of memory that has been previously
    allocated from the secure memory pool.
 
    \param p pointer to the block of memory to be resized.
    \param bytes the new size that is required.
 */
 QCA_EXPORT void *qca_secure_realloc(void *p, int bytes);
 
 namespace QCA {
 
 /**
    \class MemoryRegion qca_tools.h QtCrypto
 
    Array of bytes that may be optionally secured
 
    This class is mostly unusable on its own.  Either use it as a SecureArray
    subclass or call toByteArray() to convert to QByteArray.
 
    Note that this class is implicitly shared (that is, copy on write).
 
    \ingroup UserAPI
 */
 class QCA_EXPORT MemoryRegion
 {
 public:
     MemoryRegion();
 
     /**
        Constructs a new Memory Region from a null terminated
        character array
 
        \param str pointer to the array of data to copy
     */
     MemoryRegion(const char *str);
 
     /**
        Constructs a new MemoryRegion from the data in a
        byte array
 
        \param from the QByteArray to copy from
     */
     MemoryRegion(const QByteArray &from);
 
     /**
        Standard copy constructor
 
        \param from the MemoryRegion to copy from
     */
     MemoryRegion(const MemoryRegion &from);
     ~MemoryRegion();
 
     /**
        Standard assignment operator
 
        \param from the MemoryRegion to copy from
     */
     MemoryRegion &operator=(const MemoryRegion &from);
 
     /**
        Standard assignment operator
 
        \param from the QByteArray to copy from
     */
     MemoryRegion &operator=(const QByteArray &from);
 
     /**
        Test if the MemoryRegion is null (i.e. was created
        as a null array, and hasn't been resized).
 
        This is probably not what you are trying to do. If
        you are trying to determine whether there are any
        bytes in the array, use isEmpty() instead.
     */
     bool isNull() const;
 
     /**
        Test if the MemoryRegion is using secure memory, or not.
 
        In this context, memory is secure if it will not be paged
        out to disk.
 
        \return true if the memory region is secure
     */
     bool isSecure() const;
 
     /**
        Convert this memory region to a byte array.
 
        \note For secure data, this will make it insecure
 
        \sa data() and constData() for other ways to convert
        to an "accessible" format.
     */
     QByteArray toByteArray() const;
 
     /**
        Returns true if the size of the memory region is zero.
     */
     bool isEmpty() const;
 
     /**
        Returns the number of bytes in the memory region.
     */
     int size() const;
 
     /**
        Convert the contents of the memory region to
        a C-compatible character array. This consists
        of size() bytes, followed by a null terminator.
 
        \sa toByteArray for an alternative approach.
        \sa constData, which is equivalent to this method, but avoids
        the possibility that the compiler picks the wrong version.
     */
     const char *data() const;
 
     /**
        Convert the contents of the memory region to
        a C-compatible character array. This consists
        of size() bytes, followed by a null terminator.
 
        \sa toByteArray for an alternative approach.
        \sa data which is equivalent to this method
     */
     const char *constData() const;
 
     /**
        Obtain the value of the memory location at the specified
        position.
 
        \param index the offset into the memory region.
 
        \note The contents of a memory region are between
        0 and size()-1. The content at position size() is
        always a null terminator.
     */
     const char &at(int index) const;
 
 protected:
     /**
        Create a memory region, optionally using secure
        storage.
 
        \param secure if this is true, the memory region
        will use secure storage.
 
        \note This will create a memory region without
        any content (i.e. both isNull() and isEmpty() will
        return true.
     */
     MemoryRegion(bool secure);
 
     /**
        Create a memory region, optionally using secure
        storage.
 
        \param size the number of bytes in the memory
        region.
        \param secure if this is true, the memory region
        will use secure storage.
     */
     MemoryRegion(int size, bool secure);
 
     /**
        Create a memory region, optionally using secure
        storage.
 
        This constructor variant allows you to
        initialize the memory region from an existing
        array.
 
        \param from the byte array to copy from.
        \param secure if this is true, the memory region
        will use secure storage.
     */
     MemoryRegion(const QByteArray &from, bool secure);
 
     /**
        Convert the contents of the memory region to
        a C-compatible character array. This consists
        of size() bytes, followed by a null terminator.
     */
     char *data();
 
     /**
        Obtain the value of the memory location at the specified
        position.
 
        \param index the offset into the memory region.
 
        \note The contents of a memory region are between
        0 and size()-1. The content at position size() is
        always a null terminator.
     */
     char &at(int index);
 
     /**
        Resize the memory region to the specified size.
 
        \param size the new size of the region.
     */
     bool resize(int size);
 
     /**
        Modify the memory region to match a specified
        byte array. This resizes the memory region
        as required to match the byte array size.
 
        \param from the byte array to copy from.
        \param secure if this is true, the memory region
        will use secure storage.
     */
     void set(const QByteArray &from, bool secure);
 
     /**
        Convert the memory region to use the specified
        memory type.
 
        This may involve copying data from secure to
        insecure storage, or from insecure to secure
        storage.
 
        \param secure if true, use secure memory; otherwise
        use insecure memory.
     */
     void setSecure(bool secure);
 
 private:
     bool _secure;
     class Private;
     QSharedDataPointer<Private> d;
 };
 
 /**
    \class SecureArray qca_tools.h QtCrypto
 
    Secure array of bytes
 
    The %SecureArray provides an array of memory from a pool that is,
    at least partly, secure. In this sense, secure means that the contents
    of the memory should not be made available to other applications. By
    comparison, a QByteArray or QString may be held in pages that might be
    swapped to disk or free'd without being cleared first.
 
    Note that this class is implicitly shared (that is, copy on write).
 
    \ingroup UserAPI
 */
 class QCA_EXPORT SecureArray : public MemoryRegion
 {
 public:
     /**
        Construct a secure byte array, zero length
     */
     SecureArray();
 
     /**
        Construct a secure byte array of the specified length
 
        \param size the number of bytes in the array
        \param ch the value every byte should be set to
     */
     explicit SecureArray(int size, char ch = 0);
 
     /**
        Construct a secure byte array from a string
 
        Note that this copies, rather than references the source array.
 
        \param str the source of the data (as a null terminated string).
     */
     SecureArray(const char *str);
 
     /**
        Construct a secure byte array from a QByteArray
 
        Note that this copies, rather than references the source array.
 
        \param a the source of the data.
 
        \sa operator=()
     */
     SecureArray(const QByteArray &a);
 
     /**
        Construct a secure byte array from a MemoryRegion
 
        Note that this copies, rather than references the source array
 
        \param a the source of the data.
 
        \sa operator=()
     */
     SecureArray(const MemoryRegion &a);
 
     /**
        Construct a (shallow) copy of another secure byte array
 
        \param from the source of the data and length.
     */
     SecureArray(const SecureArray &from);
 
     ~SecureArray();
 
     /**
        Creates a reference, rather than a deep copy.
 
        \param from the array to reference
     */
     SecureArray &operator=(const SecureArray &from);
 
     /**
        Creates a copy, rather than references
 
        \param a the array to copy from
     */
     SecureArray &operator=(const QByteArray &a);
 
     /**
        Clears the contents of the array and makes it empty
     */
     void clear();
 
     /**
        Returns a reference to the byte at the index position
 
        \param index the zero-based offset to obtain
     */
     char &operator[](int index);
 
     /**
        Returns a reference to the byte at the index position
 
        \param index the zero-based offset to obtain
     */
     const char &operator[](int index) const;
 
     /**
        Pointer to the data in the secure array
 
        You can use this for memcpy and similar functions. If you are trying
        to obtain data at a particular offset, you might be better off using
        at() or operator[]
     */
     char *data();
 
     /**
        Pointer to the data in the secure array
 
        You can use this for memcpy and similar functions. If you are trying
        to obtain data at a particular offset, you might be better off using
        at() or operator[]
     */
     const char *data() const;
 
     /**
        Pointer to the data in the secure array
 
        You can use this for memcpy and similar functions. If you are trying
        to obtain data at a particular offset, you might be better off using
        at() or operator[]
     */
     const char *constData() const;
 
     /**
        Returns a reference to the byte at the index position
 
        \param index the zero-based offset to obtain
     */
     char &at(int index);
 
     /**
        Returns a reference to the byte at the index position
 
        \param index the zero-based offset to obtain
     */
     const char &at(int index) const;
 
     /**
        Returns the number of bytes in the array
     */
     int size() const;
 
     /**
        Test if the array contains any bytes.
 
        This is equivalent to testing (size() != 0). Note that if
        the array is allocated, isEmpty() is false (even if no data
        has been added)
 
        \return true if the array has zero length, otherwise false
     */
     bool isEmpty() const;
 
     /**
        Change the length of this array
        If the new length is less than the old length, the extra information
        is (safely) discarded. If the new length is equal to or greater than
        the old length, the existing data is copied into the array.
 
        \param size the new length
     */
     bool resize(int size);
 
     /**
        Fill the data array with a specified character
 
        \param fillChar the character to use as the fill
        \param fillToPosition the number of characters to fill
        to. If not specified (or -1), fills array to
        current length.
 
        \note This function does not extend the array - if
        you ask for fill beyond the current length, only
        the current length will be used.
        \note The number of characters is 1 based, so if
        you ask for fill('x', 10), it will fill from
     */
     void fill(char fillChar, int fillToPosition = -1);
 
     /**
        Copy the contents of the secure array out to a
        standard QByteArray. Note that this performs a deep copy
        of the data.
     */
     QByteArray toByteArray() const;
 
     /**
        Append a secure byte array to the end of this array
 
        \param a the array to append to this array
     */
     SecureArray &append(const SecureArray &a);
 
     /**
        Equality operator. Returns true if both arrays have the same
        data (and the same length, of course).
 
        \param other the MemoryRegion to compare to
     */
     bool operator==(const MemoryRegion &other) const;
 
     /**
        Inequality operator. Returns true if both arrays have different
        length, or the same length but different data.
 
        \param other the MemoryRegion to compare to
     */
     inline bool operator!=(const MemoryRegion &other) const
     {
         return !(*this == other);
     }
 
     /**
        Append a secure byte array to the end of this array
 
        \param a the array to append to this array
     */
     SecureArray &operator+=(const SecureArray &a);
 
 protected:
     /**
        Assign the contents of a provided byte array to this
        object.
 
        \param from the byte array to copy
     */
     void set(const SecureArray &from);
 
     /**
        Assign the contents of a provided byte array to this
        object.
 
        \param from the byte array to copy
     */
     void set(const QByteArray &from);
 };
 
 /**
    Returns an array that is the result of concatenating a and b
 
    \param a the string to put at the start of the result
    \param b the string to put at the end of the result
 */
 QCA_EXPORT const SecureArray operator+(const SecureArray &a, const SecureArray &b);
 
 /**
    \class BigInteger qca_tools.h QtCrypto
 
    Arbitrary precision integer
 
    BigInteger provides arbitrary precision integers.
    \code
 if ( BigInteger("3499543804349") ==
     BigInteger("38493290803248") + BigInteger( 343 ) )
 {
     // do something
 }
    \endcode
 
    \ingroup UserAPI
 */
 class QCA_EXPORT BigInteger
 {
 public:
     /**
        Constructor. Creates a new BigInteger, initialised to zero.
     */
     BigInteger();
 
     /**
        \overload
 
        \param n an alternative integer initialisation value.
     */
     BigInteger(int n);
 
     /**
        \overload
 
        \param c an alternative initialisation value, encoded as a character array
 
        \code
 BigInteger b ( "9890343" );
        \endcode
     */
     BigInteger(const char *c);
 
     /**
        \overload
 
        \param s an alternative initialisation value, encoded as a string
     */
     BigInteger(const QString &s);
 
     /**
        \overload
 
        \param a an alternative initialisation value, encoded as SecureArray
     */
     BigInteger(const QCA::SecureArray &a);
 
     /**
        \overload
 
        \param from an alternative initialisation value, encoded as a %BigInteger
     */
     BigInteger(const BigInteger &from);
 
     ~BigInteger();
 
     /**
        Assignment operator
 
        \param from the BigInteger to copy from
 
        \code
 BigInteger a; // a is zero
 BigInteger b( 500 );
 a = b; // a is now 500
        \endcode
     */
     BigInteger &operator=(const BigInteger &from);
 
     /**
        \overload
 
        \param s the QString containing an integer representation
 
        \sa bool fromString(const QString &s)
 
        \note it is the application's responsibility to make sure
        that the QString represents a valid integer (ie it only
        contains numbers and an optional minus sign at the start)
     */
     BigInteger &operator=(const QString &s);
 
     /**
        Increment in place operator
 
        \param b the amount to increment by
 
        \code
 BigInteger a; // a is zero
 BigInteger b( 500 );
 a += b; // a is now 500
 a += b; // a is now 1000
        \endcode
     */
     BigInteger &operator+=(const BigInteger &b);
 
     /**
        Decrement in place operator
 
        \param b the amount to decrement by
 
        \code
 BigInteger a; // a is zero
 BigInteger b( 500 );
 a -= b; // a is now -500
 a -= b; // a is now -1000
        \endcode
     */
     BigInteger &operator-=(const BigInteger &b);
 
     /**
        Multiply in place operator
 
        \param b the amount to multiply by
     */
     BigInteger &operator*=(const BigInteger &b);
 
     /**
        Divide in place operator
 
        \param b the amount to divide by
     */
     BigInteger &operator/=(const BigInteger &b);
 
     /**
        Modulo in place operator
 
        \param b the amount to divide by
     */
     BigInteger &operator%=(const BigInteger &b);
 
     /**
        Output %BigInteger as a byte array, useful for storage or
        transmission.  The format is a binary integer in sign-extended
        network-byte-order.
 
        \sa void fromArray(const SecureArray &a);
     */
     QCA::SecureArray toArray() const;
 
     /**
        Assign from an array.  The input is expected to be a binary integer
        in sign-extended network-byte-order.
 
        \param a a SecureArray that represents an integer
 
        \sa BigInteger(const SecureArray &a);
        \sa SecureArray toArray() const;
     */
     void fromArray(const QCA::SecureArray &a);
 
     /**
        Convert %BigInteger to a QString
 
        \code
 QString aString;
 BigInteger aBiggishInteger( 5878990 );
 aString = aBiggishInteger.toString(); // aString is now "5878990"
        \endcode
     */
     QString toString() const;
 
     /**
        Assign from a QString
 
        \param s a QString that represents an integer
 
        \note it is the application's responsibility to make sure
        that the QString represents a valid integer (ie it only
        contains numbers and an optional minus sign at the start)
 
        \sa BigInteger(const QString &s)
        \sa BigInteger & operator=(const QString &s)
     */
     bool fromString(const QString &s);
 
     /**
        Compare this value with another %BigInteger
 
        Normally it is more readable to use one of the operator overloads,
        so you don't need to use this method directly.
 
        \param n the BigInteger to compare with
 
        \return zero if the values are the same, negative if the argument
        is less than the value of this BigInteger, and positive if the
        argument value is greater than this BigInteger
 
        \code
 BigInteger a( "400" );
 BigInteger b( "-400" );
 BigInteger c( " 200 " );
 int result;
 result = a.compare( b );        // return positive 400 > -400
 result = a.compare( c );        // return positive,  400 > 200
 result = b.compare( c );        // return negative, -400 < 200
        \endcode
     */
     int compare(const BigInteger &n) const;
 
     /**
        Equality operator. Returns true if the two BigInteger values
        are the same, including having the same sign.
 
        \param other the BigInteger to compare to
     */
     inline bool operator==(const BigInteger &other) const
     {
         return (compare(other) == 0);
     }
 
     /**
        Inequality operator. Returns true if the two BigInteger values
        are different in magnitude, sign or both.
 
        \param other the BigInteger to compare to
     */
     inline bool operator!=(const BigInteger &other) const
     {
         return !(*this == other);
     }
 
     /**
        Less than or equal operator. Returns true if the BigInteger value
        on the left hand side is equal to or less than the BigInteger
        value on the right hand side.
 
        \param other the BigInteger to compare to
     */
     inline bool operator<=(const BigInteger &other) const
     {
         return (compare(other) <= 0);
     }
 
     /**
        Greater than or equal operator. Returns true if the BigInteger
        value on the left hand side is equal to or greater than the
        BigInteger value on the right hand side.
 
        \param other the BigInteger to compare to
     */
     inline bool operator>=(const BigInteger &other) const
     {
         return (compare(other) >= 0);
     }
 
     /**
        Less than operator. Returns true if the BigInteger value
        on the left hand side is less than the BigInteger value
        on the right hand side.
 
        \param other the BigInteger to compare to
     */
     inline bool operator<(const BigInteger &other) const
     {
         return (compare(other) < 0);
     }
 
     /**
        Greater than operator. Returns true if the BigInteger value
        on the left hand side is greater than the BigInteger value
        on the right hand side.
 
        \param other the BigInteger to compare to
     */
     inline bool operator>(const BigInteger &other) const
     {
         return (compare(other) > 0);
     }
 
 private:
     class Private;
     QSharedDataPointer<Private> d;
 };
 
 /**
    Stream operator
 
    \param stream the stream to write to
    \param b the integer to write to the stream
 
    \relates BigInteger
 */
 QCA_EXPORT QTextStream &operator<<(QTextStream &stream, const BigInteger &b);
 
 }
 
 #endif