QCA

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 <[email protected]>
4  * Copyright (C) 2004,2005 Brad Hards <[email protected]>
5  * Copyright (C) 2014-2016 Ivan Romanov <[email protected]>
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
20  * 02110-1301 USA
21  *
22  */
23 
34 #ifndef QCA_CORE_H
35 #define QCA_CORE_H
36 
37 #include "qca_export.h"
38 #include "qca_support.h"
39 #include "qca_tools.h"
40 #include "qca_version.h"
41 #include <QList>
42 #include <QSharedData>
43 #include <QSharedDataPointer>
44 #include <QString>
45 #include <QStringList>
46 
53 QCA_EXPORT int qcaVersion();
54 
61 QCA_EXPORT const char *qcaVersionStr();
62 
69 QCA_EXPORT int qcaMajorVersion();
70 
77 QCA_EXPORT int qcaMinorVersion();
78 
85 QCA_EXPORT int qcaPatchVersion();
86 
90 namespace QCA {
91 
92 class Provider;
93 class Random;
94 class CertificateCollection;
95 class Global;
96 class KeyStore;
97 class KeyStoreEntry;
98 class KeyStoreInfo;
99 class KeyStoreManager;
100 class Logger;
101 
112 
128 {
132 };
133 
141 {
144 };
145 
151 QCA_EXPORT void init();
152 
160 QCA_EXPORT void init(MemoryMode m, int prealloc);
161 
169 QCA_EXPORT void deinit();
170 
176 QCA_EXPORT bool haveSecureMemory();
177 
186 QCA_EXPORT bool haveSecureRandom();
187 
219 QCA_EXPORT bool isSupported(const char *features, const QString &provider = QString());
220 
229 QCA_EXPORT bool isSupported(const QStringList &features, const QString &provider = QString());
230 
247 QCA_EXPORT QStringList supportedFeatures();
248 
266 QCA_EXPORT QStringList defaultFeatures();
267 
286 QCA_EXPORT bool insertProvider(Provider *p, int priority = 0);
287 
300 QCA_EXPORT bool unloadProvider(const QString &name);
301 
333 QCA_EXPORT void setProviderPriority(const QString &name, int priority);
334 
348 QCA_EXPORT int providerPriority(const QString &name);
349 
359 QCA_EXPORT ProviderList providers();
360 
366 QCA_EXPORT Provider *findProvider(const QString &name);
367 
371 QCA_EXPORT Provider *defaultProvider();
372 
384 QCA_EXPORT QStringList pluginPaths();
385 
389 QCA_EXPORT void scanForPlugins();
390 
394 QCA_EXPORT void unloadAllPlugins();
395 
399 QCA_EXPORT QString pluginDiagnosticText();
400 
404 QCA_EXPORT void clearPluginDiagnosticText();
405 
413 QCA_EXPORT void appendPluginDiagnosticText(const QString &text);
414 
423 QCA_EXPORT void setProperty(const QString &name, const QVariant &value);
424 
432 QCA_EXPORT QVariant getProperty(const QString &name);
433 
442 QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config);
443 
449 QCA_EXPORT QVariantMap getProviderConfig(const QString &name);
450 
456 QCA_EXPORT void saveProviderConfig(const QString &name);
457 
461 QCA_EXPORT QString globalRandomProvider();
462 
473 QCA_EXPORT void setGlobalRandomProvider(const QString &provider);
474 
481 QCA_EXPORT Logger *logger();
482 
493 #define QCA_logTextMessage(message, severity) \
494  do { \
495  QCA::Logger::Severity s = severity; \
496  QCA::Logger * l = QCA::logger(); \
497  if (s <= l->level()) { \
498  l->logTextMessage(message, s); \
499  } \
500  } while (false)
501 
512 #define QCA_logBinaryMessage(blob, severity) \
513  do { \
514  QCA::Logger::Severity s = severity; \
515  QCA::Logger * l = QCA::logger(); \
516  if (s <= l->level()) { \
517  l->logBinaryMessage(blob, s); \
518  } \
519  } while (false)
520 
529 QCA_EXPORT bool haveSystemStore();
530 
551 QCA_EXPORT CertificateCollection systemStore();
552 
560 QCA_EXPORT QString appName();
561 
571 QCA_EXPORT void setAppName(const QString &name);
572 
593 QCA_EXPORT QString arrayToHex(const QByteArray &array);
594 
620 QCA_EXPORT QByteArray hexToArray(const QString &hexString);
621 
632 QCA_EXPORT QString arrayToBase64(const QByteArray &array);
633 
646 QCA_EXPORT QByteArray base64ToArray(const QString &base64String);
647 
659 class QCA_EXPORT Initializer
660 {
661 public:
669  explicit Initializer(MemoryMode m = Practical, int prealloc = 64);
670  ~Initializer();
671 
672  Initializer(const Initializer &) = delete;
673  Initializer &operator=(const Initializer &) = delete;
674 };
675 
700 class QCA_EXPORT KeyLength
701 {
702 public:
711  KeyLength(int min, int max, int multiple)
712  : _min(min)
713  , _max(max)
714  , _multiple(multiple)
715  {
716  }
717 
721  int minimum() const
722  {
723  return _min;
724  }
725 
729  int maximum() const
730  {
731  return _max;
732  }
733 
740  int multiple() const
741  {
742  return _multiple;
743  }
744 
745 private:
746  const int _min, _max, _multiple;
747 };
748 
764 class QCA_EXPORT Provider
765 {
766 public:
767  virtual ~Provider();
768 
769  class Context;
770 
780  virtual void init();
781 
791  virtual void deinit();
792 
801  virtual int version() const;
802 
814  virtual int qcaVersion() const = 0;
815 
833  virtual QString name() const = 0;
834 
850  virtual QStringList features() const = 0;
851 
862  virtual QString credit() const;
863 
890  virtual Context *createContext(const QString &type) = 0;
891 
916  virtual QVariantMap defaultConfig() const;
917 
927  virtual void configChanged(const QVariantMap &config);
928 };
929 
939 class QCA_EXPORT Provider::Context : public QObject
940 {
941  Q_OBJECT
942 public:
943  ~Context() override;
944 
948  Provider *provider() const;
949 
953  QString type() const;
954 
958  virtual Context *clone() const = 0;
959 
968  bool sameProvider(const Context *c) const;
969 
970 protected:
978  Context(Provider *parent, const QString &type);
979 
985  Context(const Context &from);
986 
987 private:
988  // disable assignment
989  Context &operator=(const Context &from);
990 
991  Provider *_provider;
992  QString _type;
993 };
994 
1009 class QCA_EXPORT BasicContext : public Provider::Context
1010 {
1011  Q_OBJECT
1012 public:
1013  ~BasicContext() override;
1014 
1015 protected:
1023  BasicContext(Provider *parent, const QString &type);
1024 
1030  BasicContext(const BasicContext &from);
1031 
1032 private:
1033  // disable assignment
1034  BasicContext &operator=(const BasicContext &from);
1035 };
1036 
1051 class QCA_EXPORT BufferedComputation
1052 {
1053 public:
1054  virtual ~BufferedComputation();
1055 
1059  virtual void clear() = 0;
1060 
1067  virtual void update(const MemoryRegion &a) = 0;
1068 
1072  virtual MemoryRegion final() = 0;
1073 
1086  MemoryRegion process(const MemoryRegion &a);
1087 };
1088 
1107 class QCA_EXPORT Filter
1108 {
1109 public:
1110  virtual ~Filter();
1111 
1115  virtual void clear() = 0;
1116 
1123  virtual MemoryRegion update(const MemoryRegion &a) = 0;
1124 
1129  virtual MemoryRegion final() = 0;
1130 
1136  virtual bool ok() const = 0;
1137 
1150  MemoryRegion process(const MemoryRegion &a);
1151 };
1152 
1163 class QCA_EXPORT Algorithm
1164 {
1165 public:
1171  Algorithm(const Algorithm &from);
1172 
1173  virtual ~Algorithm();
1174 
1180  Algorithm &operator=(const Algorithm &from);
1181 
1185  QString type() const;
1186 
1193  Provider *provider() const;
1194 
1195  // Note: The next five functions are not public!
1196 
1202  Provider::Context *context();
1203 
1209  const Provider::Context *context() const;
1210 
1218  void change(Provider::Context *c);
1219 
1228  void change(const QString &type, const QString &provider);
1229 
1235  Provider::Context *takeContext();
1236 
1237 protected:
1241  Algorithm();
1242 
1249  Algorithm(const QString &type, const QString &provider);
1250 
1251 private:
1252  class Private;
1254 };
1255 
1263 class QCA_EXPORT SymmetricKey : public SecureArray
1264 {
1265 public:
1269  SymmetricKey();
1270 
1278  SymmetricKey(int size);
1279 
1285  SymmetricKey(const SecureArray &a);
1286 
1292  SymmetricKey(const QByteArray &a);
1293 
1299  bool isWeakDESKey();
1300 };
1301 
1309 class QCA_EXPORT InitializationVector : public SecureArray
1310 {
1311 public:
1316 
1322  InitializationVector(int size);
1323 
1330 
1336  InitializationVector(const QByteArray &a);
1337 };
1338 
1346 class QCA_EXPORT AuthTag : public SecureArray
1347 {
1348 public:
1352  AuthTag();
1353 
1359  AuthTag(int size);
1360 
1366  AuthTag(const SecureArray &a);
1367 
1373  AuthTag(const QByteArray &a);
1374 };
1375 
1390 class QCA_EXPORT Event
1391 {
1392 public:
1398  enum Type
1399  {
1401  Token
1402  };
1403 
1416  enum Source
1417  {
1419  Data
1420  };
1421 
1431  {
1434  StylePIN
1435  };
1436 
1440  Event();
1441 
1447  Event(const Event &from);
1448 
1452  ~Event();
1453 
1459  Event &operator=(const Event &from);
1460 
1464  bool isNull() const;
1465 
1469  Type type() const;
1470 
1474  Source source() const;
1475 
1483  PasswordStyle passwordStyle() const;
1484 
1490  KeyStoreInfo keyStoreInfo() const;
1491 
1497  KeyStoreEntry keyStoreEntry() const;
1498 
1505  QString fileName() const;
1506 
1510  void *ptr() const;
1511 
1525  void setPasswordKeyStore(PasswordStyle pstyle,
1526  const KeyStoreInfo & keyStoreInfo,
1527  const KeyStoreEntry &keyStoreEntry,
1528  void * ptr);
1529 
1541  void setPasswordData(PasswordStyle pstyle, const QString &fileName, void *ptr);
1542 
1554  void setToken(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1555 
1556 private:
1557  class Private;
1559 };
1560 
1578 class QCA_EXPORT EventHandler : public QObject
1579 {
1580  Q_OBJECT
1581 public:
1587  EventHandler(QObject *parent = nullptr);
1588  ~EventHandler() override;
1589 
1595  void start();
1596 
1607  void submitPassword(int id, const SecureArray &password);
1608 
1618  void tokenOkay(int id);
1619 
1629  void reject(int id);
1630 
1631 Q_SIGNALS:
1641  void eventReady(int id, const QCA::Event &context);
1642 
1643 private:
1644  Q_DISABLE_COPY(EventHandler)
1645 
1646  class Private;
1647  friend class Private;
1648  Private *d;
1649 };
1650 
1660 class QCA_EXPORT PasswordAsker : public QObject
1661 {
1662  Q_OBJECT
1663 public:
1669  PasswordAsker(QObject *parent = nullptr);
1670  ~PasswordAsker() override;
1671 
1683  void
1684  ask(Event::PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1685 
1695  void ask(Event::PasswordStyle pstyle, const QString &fileName, void *ptr);
1696 
1700  void cancel();
1701 
1709  void waitForResponse();
1710 
1719  bool accepted() const;
1720 
1725  SecureArray password() const;
1726 
1727 Q_SIGNALS:
1734  void responseReady();
1735 
1736 private:
1737  Q_DISABLE_COPY(PasswordAsker)
1738 
1739  class Private;
1740  friend class Private;
1741  Private *d;
1742 };
1743 
1753 class QCA_EXPORT TokenAsker : public QObject
1754 {
1755  Q_OBJECT
1756 public:
1762  TokenAsker(QObject *parent = nullptr);
1763  ~TokenAsker() override;
1764 
1774  void ask(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1775 
1779  void cancel();
1780 
1787  void waitForResponse();
1788 
1794  bool accepted() const;
1795 
1796 Q_SIGNALS:
1803  void responseReady();
1804 
1805 private:
1806  Q_DISABLE_COPY(TokenAsker)
1807 
1808  class Private;
1809  friend class Private;
1810  Private *d;
1811 };
1812 
1813 }
1814 
1815 #endif
An asynchronous event.
Definition: qca_core.h:1390
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:1163
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:961
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:711
QCA_EXPORT QString pluginDiagnosticText()
Retrieve plugin diagnostic text.
User password / passphrase / PIN handler.
Definition: qca_core.h:1660
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:1416
QCA_EXPORT void scanForPlugins()
Scan for new plugins.
Algorithm provider.
Definition: qca_core.h:764
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:1578
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:1400
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:729
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.
General superclass for buffered computation algorithms.
Definition: qca_core.h:1051
QCA_EXPORT QByteArray base64ToArray(const QString &base64String)
Convert a QString containing a base64 representation of a byte array into a QByteArray.
Container for keys for symmetric encryption algorithms.
Definition: qca_core.h:1263
QCA_EXPORT bool unloadProvider(const QString &name)
Unload specified provider.
Container for authentication tag.
Definition: qca_core.h:1346
Simple container for acceptable key lengths.
Definition: qca_core.h:700
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:1433
PasswordStyle
password variation
Definition: qca_core.h:1430
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:130
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:1309
int multiple() const
Return the number of bytes that the key must be a multiple of.
Definition: qca_core.h:740
mlock and drop root if available, else mmap
Definition: qca_core.h:129
Direction
Direction settings for symmetric algorithms.
Definition: qca_core.h:140
KeyStore generated the event.
Definition: qca_core.h:1418
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:41
QCA_EXPORT QStringList pluginPaths()
Retrieve plugin paths.
Type
Type of event
Definition: qca_core.h:1398
Base class to use for primitive provider contexts.
Definition: qca_core.h:1009
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:721
QCA_EXPORT QString arrayToHex(const QByteArray &array)
Convert a byte array to printable hexadecimal representation.
QCA_EXPORT QString arrayToBase64(const QByteArray &array)
Convert a byte array to printable base64 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.
QList< Provider * > ProviderList
Convenience representation for the plugin providers.
Definition: qca_core.h:100
User should be prompted for a "Password".
Definition: qca_core.h:1432
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:142
Header file for "tool" classes used in QCA.
General superclass for filtering transformation algorithms.
Definition: qca_core.h:1107
Operate in the "reverse" direction; for example, decrypting.
Definition: qca_core.h:143
mlock, retaining root privileges
Definition: qca_core.h:131
User token handler.
Definition: qca_core.h:1753
Convenience method for initialising and cleaning up QCA.
Definition: qca_core.h:659
MemoryMode
Mode settings for memory allocation.
Definition: qca_core.h:127
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.
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Tue Oct 20 2020 23:09:27 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.