QuasarApp/qca
4
0
Fork 0
mirror of https://github.com/QuasarApp/qca.git synced 2025-04-26 19:44:32 +00:00
Code Issues Projects Releases Wiki Activity

Update the API documentation. We should now have #include <QtCrypto>

Browse Source 
everywhere, but it needs to be done one class at a time.
If you see any wrong, let me know.

CCMAIL:delta-affinix.com@lists.affinix.com

svn path=/trunk/kdesupport/qca/; revision=379674
This commit is contained in:
Brad Hards 2005-01-18 09:59:10 +00:00
parent 282d1bf00a
commit fa9d500d91
5 changed files with 242 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
include/QtCrypto/qca_basic.h
View File

@ -27,22 +27,24 @@
namespace QCA
{
/**
* Source of random numbers
*
* QCA provides a built in source of random numbers, which
* can be accessed through this class. You can also use
* an alternative random number source, by implementing
* another provider.
*
* You can select the "quality" of the random numbers. For
* best results, you should use Nonce or PublicValue for values
* that are likely to become public, and SessionKey or LongTermKey
* for those values that are more critical. All that said, please
* note that this is only a hint to the provider - it may make
* no difference at all.
*
* The normal use of this class is expected to be through the
* static members - randomChar(), randomInt() and randomArray().
\class Random qca_basic.h QtCrypto
Source of random numbers
QCA provides a built in source of random numbers, which
can be accessed through this class. You can also use
an alternative random number source, by implementing
another provider.
You can select the "quality" of the random numbers. For
best results, you should use Nonce or PublicValue for values
that are likely to become public, and SessionKey or LongTermKey
for those values that are more critical. All that said, please
note that this is only a hint to the provider - it may make
no difference at all.
The normal use of this class is expected to be through the
static members - randomChar(), randomInt() and randomArray().
*/
class QCA_EXPORT Random : public Algorithm
{
@ -134,48 +136,50 @@ namespace QCA
};
/**
* General superclass for hashing algorithms.
*
* %Hash is a superclass for the various hashing algorithms
* within %QCA. You should not need to use it directly unless you are
* adding another hashing capability to %QCA - you should be
* using a sub-class. SHA1 or RIPEMD160 are recommended for
* new applications, although MD2, MD4, MD5 or SHA0 may be
* applicable (for interoperability reasons) for some
* applications.
*
* To perform a hash, you create an object (of one of the
* sub-classes of %Hash), call update() with the data that
* needs to be hashed, and then call final(), which returns
* a QByteArray of the hash result. An example (using the SHA1
* hash, with 1000 updates of a 1000 byte string) is shown below:
* \code
* if(!QCA::isSupported("sha1"))
* printf("SHA1 not supported!\n");
* else {
* QByteArray fillerString;
* fillerString.fill('a', 1000);
*
* QCA::SHA1 shaHash;
* for (int i=0; i<1000; i++)
* shaHash.update(fillerString);
* QByteArray hashResult = shaHash.final();
* if ( "34aa973cd4c4daa4f61eeb2bdbad27316534016f" == QCA::arrayToHex(hashResult) ) {
* printf("big SHA1 is OK\n");
* } else {
* printf("big SHA1 failed\n");
* }
* }
* \endcode
*
* If you only have a simple hash requirement - a single
* string that is fully available in memory at one time -
* then you may be better off with one of the convenience
* methods. So, for example, instead of creating a QCA::SHA1
* or QCA::MD5 object, then doing a single update() and the final()
* call; you simply call QCA::SHA1().hash() or
* QCA::MD5().hash() with the data that you would otherwise
* have provided to the update() call.
\class Hash qca_basic.h QtCrypto
General superclass for hashing algorithms.
Hash is a superclass for the various hashing algorithms
within %QCA. You should not need to use it directly unless you are
adding another hashing capability to %QCA - you should be
using a sub-class. SHA1 or RIPEMD160 are recommended for
new applications, although MD2, MD4, MD5 or SHA0 may be
applicable (for interoperability reasons) for some
applications.
To perform a hash, you create an object (of one of the
sub-classes of %Hash), call update() with the data that
needs to be hashed, and then call final(), which returns
a QByteArray of the hash result. An example (using the SHA1
hash, with 1000 updates of a 1000 byte string) is shown below:
\code
if(!QCA::isSupported("sha1"))
printf("SHA1 not supported!\n");
else {
QByteArray fillerString;
fillerString.fill('a', 1000);
QCA::SHA1 shaHash;
for (int i=0; i<1000; i++)
shaHash.update(fillerString);
QByteArray hashResult = shaHash.final();
if ( "34aa973cd4c4daa4f61eeb2bdbad27316534016f" == QCA::arrayToHex(hashResult) ) {
printf("big SHA1 is OK\n");
} else {
printf("big SHA1 failed\n");
}
}
\endcode
If you only have a simple hash requirement - a single
string that is fully available in memory at one time -
then you may be better off with one of the convenience
methods. So, for example, instead of creating a QCA::SHA1
or QCA::MD5 object, then doing a single update() and the final()
call; you simply call QCA::SHA1().hash() or
QCA::MD5().hash() with the data that you would otherwise
have provided to the update() call.
*/
class QCA_EXPORT Hash : public Algorithm, public BufferedComputation
{
@ -367,13 +371,15 @@ namespace QCA
*/
/**
* General superclass for cipher (encryption / decryption) algorithms.
*
* %Cipher is a superclass for the various algorithms that perform
* low level encryption and decryption within %QCA. You should
* not need to use it directly unless you are
* adding another capability to %QCA - you should be
* using a sub-class. AES is recommended for new applications.
\class Cipher qca_basic.h QtCrypto
General superclass for cipher (encryption / decryption) algorithms.
Cipher is a superclass for the various algorithms that perform
low level encryption and decryption within %QCA. You should
not need to use it directly unless you are
adding another capability to %QCA - you should be
using a sub-class. AES is recommended for new applications.
*/
class QCA_EXPORT Cipher : public Algorithm, public Filter
{
@ -492,13 +498,15 @@ namespace QCA
};
/**
* General superclass for message authentication code (MAC) algorithms.
*
* %MessageAuthenticationCode is a superclass for the various
* message authentication code algorithms within %QCA. You should
* not need to use it directly unless you are
* adding another message authentication code capability to %QCA - you should be
* using a sub-class. HMAC using SHA1 is recommended for new applications.
\class MessageAuthenticationCode qca_basic.h QtCrypto
General superclass for message authentication code (MAC) algorithms.
MessageAuthenticationCode is a superclass for the various
message authentication code algorithms within %QCA. You should
not need to use it directly unless you are
adding another message authentication code capability to %QCA - you should be
using a sub-class. HMAC using SHA1 is recommended for new applications.
*/
class QCA_EXPORT MessageAuthenticationCode : public Algorithm, public BufferedComputation
{
@ -607,6 +615,8 @@ namespace QCA
/**
* \class SHA0 qca_basic.h QtCrypto
*
* SHA-0 cryptographic message digest hash algorithm.
*
* %SHA0 is a 160 bit hashing function, no longer recommended
@ -653,6 +663,8 @@ namespace QCA
};
/**
* \class SHA1 qca_basic.h QtCrypto
*
* SHA-1 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -707,6 +719,8 @@ namespace QCA
};
/**
* \class SHA256 qca_basic.h QtCrypto
*
* SHA-256 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -741,6 +755,8 @@ namespace QCA
};
/**
* \class SHA384 qca_basic.h QtCrypto
*
* SHA-384 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -775,6 +791,8 @@ namespace QCA
};
/**
* \class SHA512 qca_basic.h QtCrypto
*
* SHA-512 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -809,6 +827,8 @@ namespace QCA
};
/**
* \class MD2 qca_basic.h QtCrypto
*
* %MD2 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -842,6 +862,8 @@ namespace QCA
};
/**
* \class MD4 qca_basic.h QtCrypto
*
* %MD4 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -879,6 +901,8 @@ namespace QCA
};
/**
* \class MD5 qca_basic.h QtCrypto
*
* %MD5 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -914,6 +938,8 @@ namespace QCA
};
/**
* \class RIPEMD160 qca_basic.h QtCrypto
*
* %RIPEMD160 cryptographic message digest hash algorithm.
*
* This algorithm takes an arbitrary data stream, known as the
@ -967,6 +993,8 @@ namespace QCA
};
/**
* \class Blowfish qca_basic.h QtCrypto
*
* Bruce Schneier's Blowfish %Cipher
*
*/
@ -992,6 +1020,8 @@ namespace QCA
};
/**
* \class TripleDES qca_basic.h QtCrypto
*
* Triple %DES %Cipher
*
*/
@ -1018,6 +1048,8 @@ namespace QCA
};
/**
* \class DES qca_basic.h QtCrypto
*
* %DES %Cipher
*
*/
@ -1044,6 +1076,8 @@ namespace QCA
};
/**
* \class AES128 qca_basic.h QtCrypto
*
* Advanced Encryption Standard %Cipher - 128 bits
*
*/
@ -1070,6 +1104,8 @@ namespace QCA
};
/**
* \class AES192 qca_basic.h QtCrypto
*
* Advanced Encryption Standard %Cipher - 192 bits
*
*/
@ -1096,6 +1132,8 @@ namespace QCA
};
/**
* \class AES256 qca_basic.h QtCrypto
*
* Advanced Encryption Standard %Cipher - 256 bits
*
*/
@ -1122,6 +1160,8 @@ namespace QCA
};
/**
* \class HMAC qca_basic.h QtCrypto
*
* Keyed %Hash message authentication codes
*
* This algorithm takes an arbitrary data stream, known as the
@ -1176,6 +1216,8 @@ namespace QCA
};
/**
* \class KeyDerivationFunction qca_basic.h QtCrypto
*
* General superclass for key derivation algorithms.
*
* %KeyDerivationFunction is a superclass for the various
@ -1227,9 +1269,23 @@ namespace QCA
Private *d;
};
/**
\class PBKDF1 qca_basic.h QtCrypto
Password based key derivation function version 1
This class implements Password Based Key Derivation Function version 1,
as specified in RFC2898, and also in PKCS#5.
*/
class QCA_EXPORT PBKDF1 : public KeyDerivationFunction
{
public:
/**
Standard constructor
\param algorithm the name of the hashing algorithm to use
\param provider the name of the provider to use, if available
*/
PBKDF1(const QString &algorithm = "sha1", const QString &provider = QString() ) : KeyDerivationFunction(withAlgorithm("pbkdf1", algorithm), provider) {}
};
}

7
include/QtCrypto/qca_cert.h
View File

@ -32,10 +32,13 @@ namespace QCA
class PublicKey;
class PrivateKey;
/**
Certificate Request Format
*/
enum CertificateRequestFormat
{
CSR_PKCS10, // standard PKCS#10 format
CSR_SPKAC // Netscape format
CSR_PKCS10, ///< standard PKCS#10 format
CSR_SPKAC ///< Signed Public Key and Challenge (Netscape) format
};
// note: in SPKAC mode, all options are ignored except for challenge

140
include/QtCrypto/qca_core.h
View File

@ -488,11 +488,13 @@ namespace QCA
QCA_EXPORT QByteArray hexToArray(const QString &hexString);
/**
* Convenience method for initialising and cleaning up %QCA
*
* To ensure that QCA is properly initialised and cleaned up,
* it is convenient to create an Initializer object, and let it
* go out of scope at the end of %QCA usage.
\class Initializer qca_core.h QtCrypto
Convenience method for initialising and cleaning up %QCA
To ensure that QCA is properly initialised and cleaned up,
it is convenient to create an Initializer object, and let it
go out of scope at the end of %QCA usage.
*/
class QCA_EXPORT Initializer
{
@ -509,24 +511,26 @@ namespace QCA
};
/**
* Simple container for acceptable key lengths
*
* The KeyLength specifies the minimum and maximum byte sizes
* allowed for a key, as well as a "multiple" which the key
* size must evenly divide into.
*
* As an example, if the key can be 4, 8 or 12 bytes, you can
* express this as
* \code
* KeyLength keyLen( 4, 12, 4 );
* \endcode
*
* If you want to express a KeyLength that takes any number
* of bytes (including zero), you may want to use
* \code
* #include<limits>
* KeyLength( 0, std::numeric_limits<int>::max(), 1 );
* \endcode
\class KeyLength qca_core.h QtCrypto
Simple container for acceptable key lengths
The KeyLength specifies the minimum and maximum byte sizes
allowed for a key, as well as a "multiple" which the key
size must evenly divide into.
As an example, if the key can be 4, 8 or 12 bytes, you can
express this as
\code
KeyLength keyLen( 4, 12, 4 );
\endcode
If you want to express a KeyLength that takes any number
of bytes (including zero), you may want to use
\code
#include<limits>
KeyLength( 0, std::numeric_limits<int>::max(), 1 );
\endcode
*/
class QCA_EXPORT KeyLength
{
@ -565,15 +569,17 @@ namespace QCA
};
/**
* Algorithm provider
*
* %Provider represents a plugin provider (or as a special case, the
* built-in provider). This is the class you need to inherit
* from to create your own plugin. You don't normally need to
* worry about this class if you are just using existing
* QCA capabilities and plugins, however there is nothing stopping
* you from using it to obtain information about specific plugins,
* as shown in the example below.
\class Provider qca_core.h QtCrypto
Algorithm provider
Provider represents a plugin provider (or as a special case, the
built-in provider). This is the class you need to inherit
from to create your own plugin. You don't normally need to
worry about this class if you are just using existing
QCA capabilities and plugins, however there is nothing stopping
you from using it to obtain information about specific plugins,
as shown in the example below.
*/
class QCA_EXPORT Provider
{
@ -675,14 +681,16 @@ namespace QCA
};
/**
General superclass for buffered computation algorithms
\class BufferedComputation qca_core.h QtCrypto
A buffered computation is characterised by having the
algorithm take data in an incremental way, then having
the results delivered at the end. Conceptually, the
algorithm has some internal state that is modified
when you call update() and returned when you call
final().
General superclass for buffered computation algorithms
A buffered computation is characterised by having the
algorithm take data in an incremental way, then having
the results delivered at the end. Conceptually, the
algorithm has some internal state that is modified
when you call update() and returned when you call
final().
*/
class QCA_EXPORT BufferedComputation
{
@ -721,18 +729,20 @@ namespace QCA
};
/**
General superclass for filtering transformation algorithms
\class Filter qca_core.h QtCrypto
A filtering computation is characterised by having the
algorithm take input data in an incremental way, with results
delivered for each input, or block of input. Some internal
state may be managed, with the transformation completed
when final() is called.
General superclass for filtering transformation algorithms
If this seems a big vague, then you might try deriving
your class from a subclass with stronger semantics, or if your
update() function is always returning null results, and
everything comes out at final(), try BufferedComputation.
A filtering computation is characterised by having the
algorithm take input data in an incremental way, with results
delivered for each input, or block of input. Some internal
state may be managed, with the transformation completed
when final() is called.
If this seems a big vague, then you might try deriving
your class from a subclass with stronger semantics, or if your
update() function is always returning null results, and
everything comes out at final(), try BufferedComputation.
*/
class QCA_EXPORT Filter
{
@ -779,7 +789,9 @@ namespace QCA
};
/**
General superclass for an algorithm
\class Algorithm qca_core.h QtCrypto
General superclass for an algorithm
*/
class QCA_EXPORT Algorithm
{
@ -862,7 +874,9 @@ namespace QCA
};
/**
* Container for keys for symmetric encryption algorithms.
\class SymmmetricKey qca_core.h QtCrypto
Container for keys for symmetric encryption algorithms.
*/
class QCA_EXPORT SymmetricKey : public QSecureArray
{
@ -905,34 +919,36 @@ namespace QCA
};
/**
* Container for initialisation vectors and nonces
\class InitializationVector qca_core.h QtCrypto
Container for initialisation vectors and nonces
*/
class QCA_EXPORT InitializationVector : public QSecureArray
{
public:
/**
* Construct an empty (zero length) initisation vector
Construct an empty (zero length) initisation vector
*/
InitializationVector();
/**
* Construct an initialisation vector of the specified size
*
* \param size the length of the initialisation vector, in bytes
Construct an initialisation vector of the specified size
\param size the length of the initialisation vector, in bytes
*/
InitializationVector(int size);
/**
* Construct an initialisation vector from a provided byte array
*
* \param a the byte array to copy
Construct an initialisation vector from a provided byte array
\param a the byte array to copy
*/
InitializationVector(const QSecureArray &a);
/**
* Construct an initialisaton vector from a provided string
*
* \param cs the QCString to copy
Construct an initialisaton vector from a provided string
\param cs the QCString to copy
*/
InitializationVector(const QCString &cs);
};

8
include/QtCrypto/qca_textfilter.h
View File

@ -27,6 +27,8 @@
namespace QCA
{
/**
\class TextFilter qca_textfilter.h QtCrypto
Superclass for text based filtering algorithms
This differs from Filter in that it has the concept
@ -135,6 +137,8 @@ namespace QCA
};
/**
\class Hex qca_textfilter.h QtCrypto
Hexadecimal encoding / decoding
*/
class QCA_EXPORT Hex : public TextFilter
@ -197,7 +201,9 @@ namespace QCA
};
/**
%Base64 encoding / decoding
\class Base64 qca_textfilter.h QtCrypto
Base64 encoding / decoding
*/
class QCA_EXPORT Base64 : public TextFilter
{

45
include/QtCrypto/qca_tools.h
View File

@ -27,16 +27,18 @@
#include <qstring.h>
/**
* Secure array of bytes
*
* The %QSecureArray 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 QMemArray (or subclass such as QCString or QByteArray) 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).
\class QSecureArray qca_tools.h QtCrypto
Secure array of bytes
The %QSecureArray 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 QMemArray (or subclass such as QCString or QByteArray) 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).
**/
class QCA_EXPORT QSecureArray
{
@ -263,17 +265,18 @@ QCA_EXPORT bool operator==(const QSecureArray &a, const QSecureArray &b);
QCA_EXPORT bool operator!=(const QSecureArray &a, const QSecureArray &b);
/**
* Arbitrary precision integer
*
* %QBigInteger provides arbitrary precision integers.
* \code
* if ( QBigInteger("3499543804349") ==
* QBigInteger("38493290803248") + QBigInteger( 343 ) )
* {
* // do something
* }
* \endcode
*
\class QBigInteger qca_tools.h QtCrypto
Arbitrary precision integer
QBigInteger provides arbitrary precision integers.
\code
if ( QBigInteger("3499543804349") ==
QBigInteger("38493290803248") + QBigInteger( 343 ) )
{
// do something
}
\endcode
**/
class QCA_EXPORT QBigInteger
{