Qt Cryptographic Architecture: qca_core.h Source File

Qt Cryptographic Architecture

qca_core.h
Go to the documentation of this file.
1 /*
2 * qca_core.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
33 #ifndef QCA_CORE_H
34 #define QCA_CORE_H
35
36 #include <QString>
37 #include <QStringList>
38 #include <QList>
39 #include <QSharedData>
40 #include <QSharedDataPointer>
41 #include "qca_export.h"
42 #include "qca_support.h"
43 #include "qca_tools.h"
44 #include "qca_version.h"
45
52 QCA_EXPORT int qcaVersion();
53
60 QCA_EXPORT const char *qcaVersionStr();
61
68 QCA_EXPORT int qcaMajorVersion();
69
76 QCA_EXPORT int qcaMinorVersion();
77
84 QCA_EXPORT int qcaPatchVersion();
85
89 namespace QCA {
90
91 class Provider;
92 class Random;
93 class CertificateCollection;
94 class Global;
95 class KeyStore;
96 class KeyStoreEntry;
97 class KeyStoreInfo;
98 class KeyStoreManager;
99 class Logger;
100
110 typedef QList<Provider*> ProviderList;
111
126 enum MemoryMode
127 {
128 Practical,
129 Locking,
130 LockingKeepPrivileges
131 };
132
139 enum Direction
140 {
141 Encode,
142 Decode
143 };
144
150 QCA_EXPORT void init();
151
159 QCA_EXPORT void init(MemoryMode m, int prealloc);
160
168 QCA_EXPORT void deinit();
169
175 QCA_EXPORT bool haveSecureMemory();
176
185 QCA_EXPORT bool haveSecureRandom();
186
218 QCA_EXPORT bool isSupported(const char *features, const QString &provider = QString());
219
228 QCA_EXPORT bool isSupported(const QStringList &features, const QString &provider = QString());
229
246 QCA_EXPORT QStringList supportedFeatures();
247
265 QCA_EXPORT QStringList defaultFeatures();
266
285 QCA_EXPORT bool insertProvider(Provider *p, int priority = 0);
286
299 QCA_EXPORT bool unloadProvider(const QString &name);
300
332 QCA_EXPORT void setProviderPriority(const QString &name, int priority);
333
347 QCA_EXPORT int providerPriority(const QString &name);
348
358 QCA_EXPORT ProviderList providers();
359
365 QCA_EXPORT Provider *findProvider(const QString &name);
366
370 QCA_EXPORT Provider *defaultProvider();
371
383 QCA_EXPORT QStringList pluginPaths();
384
388 QCA_EXPORT void scanForPlugins();
389
393 QCA_EXPORT void unloadAllPlugins();
394
398 QCA_EXPORT QString pluginDiagnosticText();
399
403 QCA_EXPORT void clearPluginDiagnosticText();
404
412 QCA_EXPORT void appendPluginDiagnosticText(const QString &text);
413
422 QCA_EXPORT void setProperty(const QString &name, const QVariant &value);
423
431 QCA_EXPORT QVariant getProperty(const QString &name);
432
441 QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config);
442
448 QCA_EXPORT QVariantMap getProviderConfig(const QString &name);
449
455 QCA_EXPORT void saveProviderConfig(const QString &name);
456
460 QCA_EXPORT QString globalRandomProvider();
461
472 QCA_EXPORT void setGlobalRandomProvider(const QString &provider);
473
480 QCA_EXPORT Logger *logger();
481
492 #define QCA_logTextMessage(message, severity) \
493 do { \
494 register QCA::Logger::Severity s = severity; \
495 register QCA::Logger *l = QCA::logger (); \
496 if (s <= l->level ()) { \
497 l->logTextMessage (message, s); \
498 } \
499 } while (false)
500
511 #define QCA_logBinaryMessage(blob, severity) \
512 do { \
513 register QCA::Logger::Severity s = severity; \
514 register QCA::Logger *l = QCA::logger (); \
515 if (s <= l->level ()) { \
516 l->logBinaryMessage (blob, s); \
517 } \
518 } while (false)
519
528 QCA_EXPORT bool haveSystemStore();
529
550 QCA_EXPORT CertificateCollection systemStore();
551
559 QCA_EXPORT QString appName();
560
570 QCA_EXPORT void setAppName(const QString &name);
571
592 QCA_EXPORT QString arrayToHex(const QByteArray &array);
593
619 QCA_EXPORT QByteArray hexToArray(const QString &hexString);
620
632 class QCA_EXPORT Initializer
633 {
634 public:
642 explicit Initializer(MemoryMode m = Practical, int prealloc = 64);
643 ~Initializer();
644 };
645
670 class QCA_EXPORT KeyLength
671 {
672 public:
681 KeyLength(int min, int max, int multiple)
682 : _min( min ), _max(max), _multiple( multiple )
683 { }
684
688 int minimum() const { return _min; }
689
693 int maximum() const { return _max; }
694
701 int multiple() const { return _multiple; }
702
703 private:
704 const int _min, _max, _multiple;
705 };
706
722 class QCA_EXPORT Provider
723 {
724 public:
725 virtual ~Provider();
726
727 class Context;
728
738 virtual void init();
739
749 virtual void deinit();
750
759 virtual int version() const;
760
772 virtual int qcaVersion() const = 0;
773
791 virtual QString name() const = 0;
792
808 virtual QStringList features() const = 0;
809
820 virtual QString credit() const;
821
848 virtual Context *createContext(const QString &type) = 0;
849
874 virtual QVariantMap defaultConfig() const;
875
885 virtual void configChanged(const QVariantMap &config);
886 };
887
897 class QCA_EXPORT Provider::Context : public QObject
898 {
899 Q_OBJECT
900 public:
901 virtual ~Context();
902
906 Provider *provider() const;
907
911 QString type() const;
912
916 virtual Context *clone() const = 0;
917
926 bool sameProvider(const Context *c) const;
927
928 protected:
936 Context(Provider *parent, const QString &type);
937
943 Context(const Context &from);
944
945 private:
946 // disable assignment
947 Context & operator=(const Context &from);
948
949 Provider *_provider;
950 QString _type;
951 };
952
967 class QCA_EXPORT BasicContext : public Provider::Context
968 {
969 Q_OBJECT
970 public:
971 ~BasicContext();
972
973 protected:
981 BasicContext(Provider *parent, const QString &type);
982
988 BasicContext(const BasicContext &from);
989
990 private:
991 // disable assignment
992 BasicContext & operator=(const BasicContext &from);
993 };
994
1009 class QCA_EXPORT BufferedComputation
1010 {
1011 public:
1012 virtual ~BufferedComputation();
1013
1017 virtual void clear() = 0;
1018
1025 virtual void update(const MemoryRegion &a) = 0;
1026
1030 virtual MemoryRegion final() = 0;
1031
1044 MemoryRegion process(const MemoryRegion &a);
1045 };
1046
1065 class QCA_EXPORT Filter
1066 {
1067 public:
1068 virtual ~Filter();
1069
1073 virtual void clear() = 0;
1074
1081 virtual MemoryRegion update(const MemoryRegion &a) = 0;
1082
1087 virtual MemoryRegion final() = 0;
1088
1094 virtual bool ok() const = 0;
1095
1108 MemoryRegion process(const MemoryRegion &a);
1109 };
1110
1121 class QCA_EXPORT Algorithm
1122 {
1123 public:
1129 Algorithm(const Algorithm &from);
1130
1131 virtual ~Algorithm();
1132
1138 Algorithm & operator=(const Algorithm &from);
1139
1143 QString type() const;
1144
1151 Provider *provider() const;
1152
1153 // Note: The next five functions are not public!
1154
1160 Provider::Context *context();
1161
1167 const Provider::Context *context() const;
1168
1176 void change(Provider::Context *c);
1177
1186 void change(const QString &type, const QString &provider);
1187
1193 Provider::Context *takeContext();
1194
1195 protected:
1199 Algorithm();
1200
1207 Algorithm(const QString &type, const QString &provider);
1208
1209 private:
1210 class Private;
1211 QSharedDataPointer<Private> d;
1212 };
1213
1221 class QCA_EXPORT SymmetricKey : public SecureArray
1222 {
1223 public:
1227 SymmetricKey();
1228
1236 SymmetricKey(int size);
1237
1243 SymmetricKey(const SecureArray &a);
1244
1250 SymmetricKey(const QByteArray &a);
1251
1257 bool isWeakDESKey();
1258 };
1259
1267 class QCA_EXPORT InitializationVector : public SecureArray
1268 {
1269 public:
1273 InitializationVector();
1274
1280 InitializationVector(int size);
1281
1287 InitializationVector(const SecureArray &a);
1288
1294 InitializationVector(const QByteArray &a);
1295 };
1296
1311 class QCA_EXPORT Event
1312 {
1313 public:
1319 enum Type
1320 {
1321 Password,
1322 Token
1323 };
1324
1337 enum Source
1338 {
1339 KeyStore,
1340 Data
1341 };
1342
1351 enum PasswordStyle
1352 {
1353 StylePassword,
1354 StylePassphrase,
1355 StylePIN
1356 };
1357
1361 Event();
1362
1368 Event(const Event &from);
1369
1373 ~Event();
1374
1380 Event & operator=(const Event &from);
1381
1385 bool isNull() const;
1386
1390 Type type() const;
1391
1395 Source source() const;
1396
1404 PasswordStyle passwordStyle() const;
1405
1411 KeyStoreInfo keyStoreInfo() const;
1412
1418 KeyStoreEntry keyStoreEntry() const;
1419
1426 QString fileName() const;
1427
1431 void *ptr() const;
1432
1446 void setPasswordKeyStore(PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1447
1459 void setPasswordData(PasswordStyle pstyle, const QString &fileName, void *ptr);
1460
1472 void setToken(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1473
1474 private:
1475 class Private;
1476 QSharedDataPointer<Private> d;
1477 };
1478
1496 class QCA_EXPORT EventHandler : public QObject
1497 {
1498 Q_OBJECT
1499 public:
1505 EventHandler(QObject *parent = 0);
1506 ~EventHandler();
1507
1513 void start();
1514
1525 void submitPassword(int id, const SecureArray &password);
1526
1536 void tokenOkay(int id);
1537
1547 void reject(int id);
1548
1549 Q_SIGNALS:
1559 void eventReady(int id, const QCA::Event &context);
1560
1561 private:
1562 Q_DISABLE_COPY(EventHandler)
1563
1564 class Private;
1565 friend class Private;
1566 Private *d;
1567 };
1568
1578 class QCA_EXPORT PasswordAsker : public QObject
1579 {
1580 Q_OBJECT
1581 public:
1587 PasswordAsker(QObject *parent = 0);
1588 ~PasswordAsker();
1589
1601 void ask(Event::PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1602
1612 void ask(Event::PasswordStyle pstyle, const QString &fileName, void *ptr);
1613
1617 void cancel();
1618
1626 void waitForResponse();
1627
1636 bool accepted() const;
1637
1642 SecureArray password() const;
1643
1644 Q_SIGNALS:
1651 void responseReady();
1652
1653 private:
1654 Q_DISABLE_COPY(PasswordAsker)
1655
1656 class Private;
1657 friend class Private;
1658 Private *d;
1659 };
1660
1670 class QCA_EXPORT TokenAsker : public QObject
1671 {
1672 Q_OBJECT
1673 public:
1679 TokenAsker(QObject *parent = 0);
1680 ~TokenAsker();
1681
1691 void ask(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1692
1696 void cancel();
1697
1704 void waitForResponse();
1705
1711 bool accepted() const;
1712
1713 Q_SIGNALS:
1720 void responseReady();
1721
1722 private:
1723 Q_DISABLE_COPY(TokenAsker)
1724
1725 class Private;
1726 friend class Private;
1727 Private *d;
1728 };
1729
1730 }
1731
1732 #endif
QCA::Event
An asynchronous event.
Definition: qca_core.h:1311
QCA::logger
QCA_EXPORT Logger * logger()
Return a reference to the QCA Logger, which is used for diagnostics and error recording.
QCA::Algorithm
General superclass for an algorithm.
Definition: qca_core.h:1121
QCA::setProviderConfig
QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config)
Set provider configuration.
QCA::appendPluginDiagnosticText
QCA_EXPORT void appendPluginDiagnosticText(const QString &text)
Add plugin diagnostic text.
QCA::deinit
QCA_EXPORT void deinit()
Clean up routine.
QCA::Logger
A simple logging system.
Definition: qca_support.h:954
QCA::supportedFeatures
QCA_EXPORT QStringList supportedFeatures()
Generate a list of all the supported features in plugins, and in built in capabilities.
QCA::haveSecureRandom
QCA_EXPORT bool haveSecureRandom()
Test if secure random is available.
QCA::clearPluginDiagnosticText
QCA_EXPORT void clearPluginDiagnosticText()
Clear plugin diagnostic text.
QCA::KeyLength::KeyLength
KeyLength(int min, int max, int multiple)
Construct a KeyLength object.
Definition: qca_core.h:681
qca_version.h
Header file with QCA version.
QCA::pluginDiagnosticText
QCA_EXPORT QString pluginDiagnosticText()
Retrieve plugin diagnostic text.
QCA::PasswordAsker
User password / passphrase / PIN handler.
Definition: qca_core.h:1578
QCA::setProviderPriority
QCA_EXPORT void setProviderPriority(const QString &name, int priority)
Change the priority of a specified provider.
QCA::Event::Source
Source
Source of the event
Definition: qca_core.h:1337
QCA::scanForPlugins
QCA_EXPORT void scanForPlugins()
Scan for new plugins.
QCA::Provider
Algorithm provider.
Definition: qca_core.h:722
QCA::KeyStoreInfo
Key store information, outside of a KeyStore object.
Definition: qca_keystore.h:623
QCA::EventHandler
Interface class for password / passphrase / PIN and token handlers.
Definition: qca_core.h:1496
QCA::haveSystemStore
QCA_EXPORT bool haveSystemStore()
Test if QCA can access the root CA certificates.
qca_support.h
Header file for "support" classes used in QCA.
QObject
QCA::setAppName
QCA_EXPORT void setAppName(const QString &name)
Set the application name that will be used by SASL server mode.
QCA::Event::Password
Asking for a password, PIN or passphrase.
Definition: qca_core.h:1321
QCA::providers
QCA_EXPORT ProviderList providers()
Return a list of the current providers.
QCA::unloadAllPlugins
QCA_EXPORT void unloadAllPlugins()
Unload the current plugins.
QCA::getProviderConfig
QCA_EXPORT QVariantMap getProviderConfig(const QString &name)
Retrieve provider configuration.
qcaVersionStr
QCA_EXPORT const char * qcaVersionStr()
The current version of QCA.
QCA::ProviderList
QList< Provider * > ProviderList
Convenience representation for the plugin providers.
Definition: qca_core.h:99
QCA::BufferedComputation
General superclass for buffered computation algorithms.
Definition: qca_core.h:1009
QCA::SymmetricKey
Container for keys for symmetric encryption algorithms.
Definition: qca_core.h:1221
QCA::unloadProvider
QCA_EXPORT bool unloadProvider(const QString &name)
Unload specified provider.
QCA::KeyLength
Simple container for acceptable key lengths.
Definition: qca_core.h:670
QCA::defaultProvider
QCA_EXPORT Provider * defaultProvider()
Return the default provider.
QCA::isSupported
QCA_EXPORT bool isSupported(const char *features, const QString &provider=QString())
Test if a capability (algorithm) is available.
QCA::Event::StylePassphrase
User should be prompted for a "Passphrase".
Definition: qca_core.h:1354
QCA::Event::PasswordStyle
PasswordStyle
password variation
Definition: qca_core.h:1351
qca_export.h
Preprocessor magic to allow export of library symbols.
QCA::defaultFeatures
QCA_EXPORT QStringList defaultFeatures()
Generate a list of the built in features.
QCA::Locking
mlock and drop root
Definition: qca_core.h:129
QCA::insertProvider
QCA_EXPORT bool insertProvider(Provider *p, int priority=0)
Add a provider to the current list of providers.
QCA::providerPriority
QCA_EXPORT int providerPriority(const QString &name)
Return the priority of a specified provider.
QCA::InitializationVector
Container for initialisation vectors and nonces.
Definition: qca_core.h:1267
QCA::Practical
mlock and drop root if available, else mmap
Definition: qca_core.h:128
QCA::Direction
Direction
Direction settings for symmetric algorithms.
Definition: qca_core.h:139
QCA::Event::KeyStore
KeyStore generated the event.
Definition: qca_core.h:1339
QCA
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:47
QCA::pluginPaths
QCA_EXPORT QStringList pluginPaths()
Retrieve plugin paths.
QCA::Event::Type
Type
Type of event
Definition: qca_core.h:1319
QCA::BasicContext
Base class to use for primitive provider contexts.
Definition: qca_core.h:967
QCA::KeyStoreEntry
Single entry in a KeyStore.
Definition: qca_keystore.h:140
QCA::findProvider
QCA_EXPORT Provider * findProvider(const QString &name)
Return the named provider, or 0 if not found.
QCA::systemStore
QCA_EXPORT CertificateCollection systemStore()
Get system-wide root Certificate Authority (CA) certificates.
QCA::arrayToHex
QCA_EXPORT QString arrayToHex(const QByteArray &array)
Convert a byte array to printable hexadecimal representation.
QCA::init
QCA_EXPORT void init()
Initialise QCA.
QCA::KeyLength::minimum
int minimum() const
Obtain the minimum length for the key, in bytes.
Definition: qca_core.h:688
QCA::SecureArray
Secure array of bytes.
Definition: qca_tools.h:316
QCA::hexToArray
QCA_EXPORT QByteArray hexToArray(const QString &hexString)
Convert a QString containing a hexadecimal representation of a byte array into a QByteArray.
qcaVersion
QCA_EXPORT int qcaVersion()
The current version of QCA.
QCA::Event::StylePassword
User should be prompted for a "Password".
Definition: qca_core.h:1353
qcaMinorVersion
QCA_EXPORT int qcaMinorVersion()
The current version of QCA.
QCA::setGlobalRandomProvider
QCA_EXPORT void setGlobalRandomProvider(const QString &provider)
Change the global random number provider.
QCA::Encode
Operate in the "forward" direction; for example, encrypting.
Definition: qca_core.h:141
qca_tools.h
Header file for "tool" classes used in QCA.
QCA::Filter
General superclass for filtering transformation algorithms.
Definition: qca_core.h:1065
QCA::Decode
Operate in the "reverse" direction; for example, decrypting.
Definition: qca_core.h:142
QCA::LockingKeepPrivileges
mlock, retaining root privileges
Definition: qca_core.h:130
QCA::TokenAsker
User token handler.
Definition: qca_core.h:1670
QCA::Initializer
Convenience method for initialising and cleaning up QCA.
Definition: qca_core.h:632
QCA::MemoryMode
MemoryMode
Mode settings for memory allocation.
Definition: qca_core.h:126
qcaMajorVersion
QCA_EXPORT int qcaMajorVersion()
The current version of QCA.
QCA::saveProviderConfig
QCA_EXPORT void saveProviderConfig(const QString &name)
Save provider configuration to persistent storage.
QCA::globalRandomProvider
QCA_EXPORT QString globalRandomProvider()
Return the name of the global random number provider.
QCA::Provider::Context
Internal context class used for the plugin.
QCA::setProperty
QCA_EXPORT void setProperty(const QString &name, const QVariant &value)
Set a global property.
QCA::getProperty
QCA_EXPORT QVariant getProperty(const QString &name)
Retrieve a global property.
QCA::KeyLength::maximum
int maximum() const
Obtain the maximum length for the key, in bytes.
Definition: qca_core.h:693
QCA::KeyLength::multiple
int multiple() const
Return the number of bytes that the key must be a multiple of.
Definition: qca_core.h:701
QCA::haveSecureMemory
QCA_EXPORT bool haveSecureMemory()
Test if secure storage memory is available.
qcaPatchVersion
QCA_EXPORT int qcaPatchVersion()
The current version of QCA.
QList
QCA::MemoryRegion
Array of bytes that may be optionally secured.
Definition: qca_tools.h:90
QCA::appName
QCA_EXPORT QString appName()
Get the application name that will be used by SASL server mode.