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 
111 
127 {
131 };
132 
140 {
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:
1274 
1280  InitializationVector(int size);
1281 
1288 
1294  InitializationVector(const QByteArray &a);
1295 };
1296 
1311 class QCA_EXPORT Event
1312 {
1313 public:
1319  enum Type
1320  {
1322  Token
1323  };
1324 
1337  enum Source
1338  {
1340  Data
1341  };
1342 
1352  {
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
An asynchronous event.
Definition: qca_core.h:1311
QCA_EXPORT Logger * logger()
Return a reference to the QCA Logger, which is used for diagnostics and error recording.
General superclass for an algorithm.
Definition: qca_core.h:1121
QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config)
Set provider configuration.
QCA_EXPORT void appendPluginDiagnosticText(const QString &text)
Add plugin diagnostic text.
QCA_EXPORT void deinit()
Clean up routine.
A simple logging system.
Definition: qca_support.h:954
QCA_EXPORT QStringList supportedFeatures()
Generate a list of all the supported features in plugins, and in built in capabilities.
QCA_EXPORT bool haveSecureRandom()
Test if secure random is available.
QCA_EXPORT void clearPluginDiagnosticText()
Clear plugin diagnostic text.
KeyLength(int min, int max, int multiple)
Construct a KeyLength object.
Definition: qca_core.h:681
Header file with QCA version.
QCA_EXPORT QString pluginDiagnosticText()
Retrieve plugin diagnostic text.
User password / passphrase / PIN handler.
Definition: qca_core.h:1578
QCA_EXPORT void setProviderPriority(const QString &name, int priority)
Change the priority of a specified provider.
Source
Source of the event
Definition: qca_core.h:1337
QCA_EXPORT void scanForPlugins()
Scan for new plugins.
Algorithm provider.
Definition: qca_core.h:722
Key store information, outside of a KeyStore object.
Definition: qca_keystore.h:623
Interface class for password / passphrase / PIN and token handlers.
Definition: qca_core.h:1496
QCA_EXPORT bool haveSystemStore()
Test if QCA can access the root CA certificates.
Header file for "support" classes used in QCA.
QCA_EXPORT void setAppName(const QString &name)
Set the application name that will be used by SASL server mode.
Asking for a password, PIN or passphrase.
Definition: qca_core.h:1321
QCA_EXPORT ProviderList providers()
Return a list of the current providers.
int maximum() const
Obtain the maximum length for the key, in bytes.
Definition: qca_core.h:693
QCA_EXPORT void unloadAllPlugins()
Unload the current plugins.
QCA_EXPORT QVariantMap getProviderConfig(const QString &name)
Retrieve provider configuration.
QCA_EXPORT const char * qcaVersionStr()
The current version of QCA.
QList< Provider * > ProviderList
Convenience representation for the plugin providers.
Definition: qca_core.h:99
General superclass for buffered computation algorithms.
Definition: qca_core.h:1009
Container for keys for symmetric encryption algorithms.
Definition: qca_core.h:1221
QCA_EXPORT bool unloadProvider(const QString &name)
Unload specified provider.
Simple container for acceptable key lengths.
Definition: qca_core.h:670
QCA_EXPORT Provider * defaultProvider()
Return the default provider.
QCA_EXPORT bool isSupported(const char *features, const QString &provider=QString())
Test if a capability (algorithm) is available.
User should be prompted for a "Passphrase".
Definition: qca_core.h:1354
PasswordStyle
password variation
Definition: qca_core.h:1351
Preprocessor magic to allow export of library symbols.
QCA_EXPORT QStringList defaultFeatures()
Generate a list of the built in features.
mlock and drop root
Definition: qca_core.h:129
QCA_EXPORT bool insertProvider(Provider *p, int priority=0)
Add a provider to the current list of providers.
QCA_EXPORT int providerPriority(const QString &name)
Return the priority of a specified provider.
Container for initialisation vectors and nonces.
Definition: qca_core.h:1267
int multiple() const
Return the number of bytes that the key must be a multiple of.
Definition: qca_core.h:701
mlock and drop root if available, else mmap
Definition: qca_core.h:128
Direction
Direction settings for symmetric algorithms.
Definition: qca_core.h:139
KeyStore generated the event.
Definition: qca_core.h:1339
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:47
QCA_EXPORT QStringList pluginPaths()
Retrieve plugin paths.
Type
Type of event
Definition: qca_core.h:1319
Base class to use for primitive provider contexts.
Definition: qca_core.h:967
Single entry in a KeyStore.
Definition: qca_keystore.h:140
QCA_EXPORT Provider * findProvider(const QString &name)
Return the named provider, or 0 if not found.
QCA_EXPORT CertificateCollection systemStore()
Get system-wide root Certificate Authority (CA) certificates.
int minimum() const
Obtain the minimum length for the key, in bytes.
Definition: qca_core.h:688
QCA_EXPORT QString arrayToHex(const QByteArray &array)
Convert a byte array to printable hexadecimal representation.
QCA_EXPORT void init()
Initialise QCA.
Secure array of bytes.
Definition: qca_tools.h:316
QCA_EXPORT QByteArray hexToArray(const QString &hexString)
Convert a QString containing a hexadecimal representation of a byte array into a QByteArray.
QCA_EXPORT int qcaVersion()
The current version of QCA.
User should be prompted for a "Password".
Definition: qca_core.h:1353
QCA_EXPORT int qcaMinorVersion()
The current version of QCA.
QCA_EXPORT void setGlobalRandomProvider(const QString &provider)
Change the global random number provider.
Operate in the "forward" direction; for example, encrypting.
Definition: qca_core.h:141
Header file for "tool" classes used in QCA.
General superclass for filtering transformation algorithms.
Definition: qca_core.h:1065
Operate in the "reverse" direction; for example, decrypting.
Definition: qca_core.h:142
mlock, retaining root privileges
Definition: qca_core.h:130
User token handler.
Definition: qca_core.h:1670
Convenience method for initialising and cleaning up QCA.
Definition: qca_core.h:632
MemoryMode
Mode settings for memory allocation.
Definition: qca_core.h:126
QCA_EXPORT int qcaMajorVersion()
The current version of QCA.
QCA_EXPORT void saveProviderConfig(const QString &name)
Save provider configuration to persistent storage.
QCA_EXPORT QString globalRandomProvider()
Return the name of the global random number provider.
Internal context class used for the plugin.
QCA_EXPORT void setProperty(const QString &name, const QVariant &value)
Set a global property.
QCA_EXPORT QVariant getProperty(const QString &name)
Retrieve a global property.
QCA_EXPORT bool haveSecureMemory()
Test if secure storage memory is available.
QCA_EXPORT int qcaPatchVersion()
The current version of QCA.
Array of bytes that may be optionally secured.
Definition: qca_tools.h:90
QCA_EXPORT QString appName()
Get the application name that will be used by SASL server mode.