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 * Copyright (C) 2014-2016 Ivan Romanov <drizt@land.ru>
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
53QCA_EXPORT int qcaVersion();
54
61QCA_EXPORT const char *qcaVersionStr();
62
69QCA_EXPORT int qcaMajorVersion();
70
77QCA_EXPORT int qcaMinorVersion();
78
85QCA_EXPORT int qcaPatchVersion();
86
90namespace QCA {
91
92class Provider;
93class Random;
94class CertificateCollection;
95class Global;
96class KeyStore;
97class KeyStoreEntry;
98class KeyStoreInfo;
99class KeyStoreManager;
100class Logger;
101
112
133
145
151QCA_EXPORT void init();
152
160QCA_EXPORT void init(MemoryMode m, int prealloc);
161
169QCA_EXPORT void deinit();
170
176QCA_EXPORT bool haveSecureMemory();
177
186QCA_EXPORT bool haveSecureRandom();
187
219QCA_EXPORT bool isSupported(const char *features, const QString &provider = QString());
220
229QCA_EXPORT bool isSupported(const QStringList &features, const QString &provider = QString());
230
247QCA_EXPORT QStringList supportedFeatures();
248
266QCA_EXPORT QStringList defaultFeatures();
267
286QCA_EXPORT bool insertProvider(Provider *p, int priority = 0);
287
300QCA_EXPORT bool unloadProvider(const QString &name);
301
333QCA_EXPORT void setProviderPriority(const QString &name, int priority);
334
348QCA_EXPORT int providerPriority(const QString &name);
349
360
366QCA_EXPORT Provider *findProvider(const QString &name);
367
372
384QCA_EXPORT QStringList pluginPaths();
385
389QCA_EXPORT void scanForPlugins();
390
394QCA_EXPORT void unloadAllPlugins();
395
399QCA_EXPORT QString pluginDiagnosticText();
400
405
413QCA_EXPORT void appendPluginDiagnosticText(const QString &text);
414
423QCA_EXPORT void setProperty(const QString &name, const QVariant &value);
424
432QCA_EXPORT QVariant getProperty(const QString &name);
433
442QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config);
443
449QCA_EXPORT QVariantMap getProviderConfig(const QString &name);
450
456QCA_EXPORT void saveProviderConfig(const QString &name);
457
461QCA_EXPORT QString globalRandomProvider();
462
473QCA_EXPORT void setGlobalRandomProvider(const QString &provider);
474
481QCA_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
529QCA_EXPORT bool haveSystemStore();
530
552
560QCA_EXPORT QString appName();
561
571QCA_EXPORT void setAppName(const QString &name);
572
593QCA_EXPORT QString arrayToHex(const QByteArray &array);
594
620QCA_EXPORT QByteArray hexToArray(const QString &hexString);
621
632QCA_EXPORT QString arrayToBase64(const QByteArray &array);
633
646QCA_EXPORT QByteArray base64ToArray(const QString &base64String);
647
659class QCA_EXPORT Initializer
660{
661public:
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
700class QCA_EXPORT KeyLength
701{
702public:
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
745private:
746 const int _min, _max, _multiple;
747};
748
764class QCA_EXPORT Provider
765{
766public:
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
939class QCA_EXPORT Provider::Context : public QObject
940{
941 Q_OBJECT
942public:
943 ~Context() override;
944
949
953 QString type() const;
954
958 virtual Context *clone() const = 0;
959
968 bool sameProvider(const Context *c) const;
969
970protected:
978 Context(Provider *parent, const QString &type);
979
985 Context(const Context &from);
986
987private:
988 // disable assignment
989 Context &operator=(const Context &from);
990
991 Provider *_provider;
992 QString _type;
993};
994
1009class QCA_EXPORT BasicContext : public Provider::Context
1010{
1011 Q_OBJECT
1012public:
1013 ~BasicContext() override;
1014
1015protected:
1023 BasicContext(Provider *parent, const QString &type);
1024
1031
1032private:
1033 // disable assignment
1034 BasicContext &operator=(const BasicContext &from);
1035};
1036
1051class QCA_EXPORT BufferedComputation
1052{
1053public:
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
1087};
1088
1107class QCA_EXPORT Filter
1108{
1109public:
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
1151};
1152
1163class QCA_EXPORT Algorithm
1164{
1165public:
1171 Algorithm(const Algorithm &from);
1172
1173 virtual ~Algorithm();
1174
1181
1185 QString type() const;
1186
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
1237protected:
1242
1249 Algorithm(const QString &type, const QString &provider);
1250
1251private:
1252 class Private;
1253 QSharedDataPointer<Private> d;
1254};
1255
1263class QCA_EXPORT SymmetricKey : public SecureArray
1264{
1265public:
1270
1278 SymmetricKey(int size);
1279
1286
1292 SymmetricKey(const QByteArray &a);
1293
1300};
1301
1309class QCA_EXPORT InitializationVector : public SecureArray
1310{
1311public:
1316
1323
1330
1336 InitializationVector(const QByteArray &a);
1337};
1338
1346class QCA_EXPORT AuthTag : public SecureArray
1347{
1348public:
1353
1359 AuthTag(int size);
1360
1367
1373 AuthTag(const QByteArray &a);
1374};
1375
1390class QCA_EXPORT Event
1391{
1392public:
1398 enum Type
1399 {
1401 Token
1403
1417 {
1419 Data
1421
1436
1441
1447 Event(const Event &from);
1448
1453
1459 Event &operator=(const Event &from);
1460
1464 bool isNull() const;
1465
1469 Type type() const;
1470
1475
1484
1491
1498
1505 QString fileName() const;
1506
1510 void *ptr() const;
1511
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
1556private:
1557 class Private;
1558 QSharedDataPointer<Private> d;
1559};
1560
1578class QCA_EXPORT EventHandler : public QObject
1579{
1580 Q_OBJECT
1581public:
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
1631Q_SIGNALS:
1641 void eventReady(int id, const QCA::Event &context);
1642
1643private:
1644 Q_DISABLE_COPY(EventHandler)
1645
1646 class Private;
1647 friend class Private;
1648 Private *d;
1649};
1650
1660class QCA_EXPORT PasswordAsker : public QObject
1661{
1662 Q_OBJECT
1663public:
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
1710
1719 bool accepted() const;
1720
1726
1727Q_SIGNALS:
1735
1736private:
1737 Q_DISABLE_COPY(PasswordAsker)
1738
1739 class Private;
1740 friend class Private;
1741 Private *d;
1742};
1743
1753class QCA_EXPORT TokenAsker : public QObject
1754{
1755 Q_OBJECT
1756public:
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
1788
1794 bool accepted() const;
1795
1796Q_SIGNALS:
1804
1805private:
1806 Q_DISABLE_COPY(TokenAsker)
1807
1808 class Private;
1809 friend class Private;
1810 Private *d;
1811};
1812
1813}
1814
1815#endif
General superclass for an algorithm.
Definition qca_core.h:1164
QString type() const
The name of the algorithm type.
Algorithm()
Constructor for empty algorithm.
Algorithm(const QString &type, const QString &provider)
Constructor of a particular algorithm.
void change(Provider::Context *c)
Provider * provider() const
The name of the provider.
void change(const QString &type, const QString &provider)
Algorithm(const Algorithm &from)
Standard copy constructor.
Provider::Context * takeContext()
const Provider::Context * context() const
Algorithm & operator=(const Algorithm &from)
Assignment operator.
Provider::Context * context()
Container for authentication tag.
Definition qca_core.h:1347
AuthTag(const QByteArray &a)
Construct an authentication tag from a provided byte array.
AuthTag(const SecureArray &a)
Construct an authentication tag from a provided byte array.
AuthTag()
Construct an empty authentication tag.
AuthTag(int size)
Construct an empty authentication tag of the specified size.
Base class to use for primitive provider contexts.
Definition qca_core.h:1010
BasicContext(Provider *parent, const QString &type)
Standard constructor.
BasicContext(const BasicContext &from)
Copy constructor.
General superclass for buffered computation algorithms.
Definition qca_core.h:1052
virtual void clear()=0
Reset the internal state.
MemoryRegion process(const MemoryRegion &a)
Perform an "all in one" update, returning the result.
virtual void update(const MemoryRegion &a)=0
Update the internal state with a byte array.
Bundle of Certificates and CRLs.
Definition qca_cert.h:1929
Interface class for password / passphrase / PIN and token handlers.
Definition qca_core.h:1579
EventHandler(QObject *parent=nullptr)
Constructor.
void submitPassword(int id, const SecureArray &password)
function to call to return the user provided password, passphrase or PIN.
void eventReady(int id, const QCA::Event &context)
signal emitted when an Event requires attention.
void reject(int id)
function to call to indicate that the user declined to provide a password, passphrase,...
void tokenOkay(int id)
function to call to indicate that the token has been inserted by the user.
void start()
mandatory function to call after connecting the signal to a slot in your application specific passwor...
An asynchronous event.
Definition qca_core.h:1391
Source
Source of the event
Definition qca_core.h:1417
@ KeyStore
KeyStore generated the event.
Definition qca_core.h:1418
~Event()
Destructor.
Event(const Event &from)
Copy constructor.
QString fileName() const
Name or other identifier for the file or byte array associated with this event.
PasswordStyle passwordStyle() const
the style of password required.
Type type() const
the Type of this event
void setPasswordKeyStore(PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr)
Set the values for this Event.
void setToken(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr)
Set the values for this Event.
KeyStoreEntry keyStoreEntry() const
The KeyStoreEntry associated with this event.
void * ptr() const
opaque data
KeyStoreInfo keyStoreInfo() const
The info of the KeyStore associated with this event.
bool isNull() const
test if this event has been setup correctly
Source source() const
the Source of this event
Type
Type of event
Definition qca_core.h:1399
@ Password
Asking for a password, PIN or passphrase.
Definition qca_core.h:1400
Event()
Constructor.
PasswordStyle
password variation
Definition qca_core.h:1431
@ StylePassphrase
User should be prompted for a "Passphrase".
Definition qca_core.h:1433
@ StylePassword
User should be prompted for a "Password".
Definition qca_core.h:1432
void setPasswordData(PasswordStyle pstyle, const QString &fileName, void *ptr)
Set the values for this Event.
Event & operator=(const Event &from)
Assignment operator.
General superclass for filtering transformation algorithms.
Definition qca_core.h:1108
MemoryRegion process(const MemoryRegion &a)
Perform an "all in one" update, returning the result.
virtual bool ok() const =0
Test if an update() or final() call succeeded.
virtual MemoryRegion update(const MemoryRegion &a)=0
Process more data, returning the corresponding filtered version of the data.
virtual void clear()=0
Reset the internal state.
Container for initialisation vectors and nonces.
Definition qca_core.h:1310
InitializationVector(int size)
Construct an initialization vector of the specified size.
InitializationVector(const QByteArray &a)
Construct an initialization vector from a provided byte array.
InitializationVector(const SecureArray &a)
Construct an initialization vector from a provided byte array.
InitializationVector()
Construct an empty (zero length) initialization vector.
Convenience method for initialising and cleaning up QCA.
Definition qca_core.h:660
Initializer(MemoryMode m=Practical, int prealloc=64)
Standard constructor.
Simple container for acceptable key lengths.
Definition qca_core.h:701
KeyLength(int min, int max, int multiple)
Construct a KeyLength object.
Definition qca_core.h:711
int minimum() const
Obtain the minimum length for the key, in bytes.
Definition qca_core.h:721
int multiple() const
Return the number of bytes that the key must be a multiple of.
Definition qca_core.h:740
int maximum() const
Obtain the maximum length for the key, in bytes.
Definition qca_core.h:729
Single entry in a KeyStore.
Definition qca_keystore.h:141
Key store information, outside of a KeyStore object.
Definition qca_keystore.h:624
A simple logging system.
Definition qca_support.h:963
Array of bytes that may be optionally secured.
Definition qca_tools.h:91
User password / passphrase / PIN handler.
Definition qca_core.h:1661
void ask(Event::PasswordStyle pstyle, const QString &fileName, void *ptr)
queue a password / passphrase request associated with a file
void responseReady()
Emitted when the asker process has been completed.
void waitForResponse()
Block until the password / passphrase request is completed.
PasswordAsker(QObject *parent=nullptr)
Construct a new asker.
void cancel()
Cancel the pending password / passphrase request.
bool accepted() const
Determine whether the password / passphrase was accepted or not.
void ask(Event::PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr)
queue a password / passphrase request associated with a key store
SecureArray password() const
The password / passphrase / PIN provided by the user in response to the asker request.
Internal context class used for the plugin.
Algorithm provider.
Definition qca_core.h:765
virtual int qcaVersion() const =0
Target QCA version for the provider.
bool sameProvider(const Context *c) const
Test if two Contexts have the same Provider.
virtual void init()
Initialisation routine.
virtual QStringList features() const =0
Context(Provider *parent, const QString &type)
Standard constructor.
virtual Context * clone() const =0
Create a duplicate of this Context.
virtual QString credit() const
Optional credit text for the provider.
virtual Context * createContext(const QString &type)=0
QString type() const
The type of context, as passed to the constructor.
Context(const Context &from)
Copy constructor.
virtual QVariantMap defaultConfig() const
virtual void deinit()
Deinitialisation routine.
virtual void configChanged(const QVariantMap &config)
Method to set the configuration options.
Provider * provider() const
The Provider associated with this Context.
virtual QString name() const =0
virtual int version() const
Version number of the plugin.
Secure array of bytes.
Definition qca_tools.h:317
Container for keys for symmetric encryption algorithms.
Definition qca_core.h:1264
SymmetricKey(const SecureArray &a)
Construct a key from a provided byte array.
SymmetricKey(int size)
Construct an key of specified size, with random contents.
SymmetricKey(const QByteArray &a)
Construct a key from a provided byte array.
SymmetricKey()
Construct an empty (zero length) key.
bool isWeakDESKey()
Test for weak DES keys.
User token handler.
Definition qca_core.h:1754
void waitForResponse()
Block until the token request is completed.
void cancel()
Cancel the pending password / passphrase request.
void responseReady()
Emitted when the asker process has been completed.
bool accepted() const
Test if the token request was accepted or not.
TokenAsker(QObject *parent=nullptr)
Construct a new asker.
void ask(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr)
queue a token request associated with a key store
QCA - the Qt Cryptographic Architecture.
Definition qca_basic.h:41
QCA_EXPORT int providerPriority(const QString &name)
Return the priority of a specified provider.
QCA_EXPORT void setGlobalRandomProvider(const QString &provider)
Change the global random number provider.
QCA_EXPORT void setProviderPriority(const QString &name, int priority)
Change the priority of a specified provider.
QCA_EXPORT void init()
Initialise QCA.
QCA_EXPORT void scanForPlugins()
Scan for new plugins.
QCA_EXPORT void unloadAllPlugins()
Unload the current plugins.
QCA_EXPORT bool haveSecureMemory()
Test if secure storage memory is available.
QCA_EXPORT QString appName()
Get the application name that will be used by SASL server mode.
QCA_EXPORT bool haveSecureRandom()
Test if secure random is available.
QCA_EXPORT QString arrayToHex(const QByteArray &array)
Convert a byte array to printable hexadecimal representation.
QCA_EXPORT bool insertProvider(Provider *p, int priority=0)
Add a provider to the current list of providers.
QCA_EXPORT Logger * logger()
Return a reference to the QCA Logger, which is used for diagnostics and error recording.
QList< Provider * > ProviderList
Convenience representation for the plugin providers.
Definition qca_core.h:111
QCA_EXPORT bool haveSystemStore()
Test if QCA can access the root CA certificates.
QCA_EXPORT bool isSupported(const char *features, const QString &provider=QString())
Test if a capability (algorithm) is available.
MemoryMode
Mode settings for memory allocation.
Definition qca_core.h:128
@ Locking
mlock and drop root
Definition qca_core.h:130
@ Practical
mlock and drop root if available, else mmap
Definition qca_core.h:129
@ LockingKeepPrivileges
mlock, retaining root privileges
Definition qca_core.h:131
QCA_EXPORT QByteArray hexToArray(const QString &hexString)
Convert a QString containing a hexadecimal representation of a byte array into a QByteArray.
Direction
Direction settings for symmetric algorithms.
Definition qca_core.h:141
@ Encode
Operate in the "forward" direction; for example, encrypting.
Definition qca_core.h:142
@ Decode
Operate in the "reverse" direction; for example, decrypting.
Definition qca_core.h:143
QCA_EXPORT Provider * defaultProvider()
Return the default provider.
QCA_EXPORT QStringList supportedFeatures()
Generate a list of all the supported features in plugins, and in built in capabilities.
QCA_EXPORT QString pluginDiagnosticText()
Retrieve plugin diagnostic text.
QCA_EXPORT QVariant getProperty(const QString &name)
Retrieve a global property.
QCA_EXPORT QVariantMap getProviderConfig(const QString &name)
Retrieve provider configuration.
QCA_EXPORT void deinit()
Clean up routine.
QCA_EXPORT void clearPluginDiagnosticText()
Clear plugin diagnostic text.
QCA_EXPORT void appendPluginDiagnosticText(const QString &text)
Add plugin diagnostic text.
QCA_EXPORT ProviderList providers()
Return a list of the current providers.
QCA_EXPORT void setProperty(const QString &name, const QVariant &value)
Set a global property.
QCA_EXPORT QStringList defaultFeatures()
Generate a list of the built in features.
QCA_EXPORT bool unloadProvider(const QString &name)
Unload specified provider.
QCA_EXPORT void saveProviderConfig(const QString &name)
Save provider configuration to persistent storage.
QCA_EXPORT QStringList pluginPaths()
Retrieve plugin paths.
QCA_EXPORT QByteArray base64ToArray(const QString &base64String)
Convert a QString containing a base64 representation of a byte array into a QByteArray.
QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config)
Set provider configuration.
QCA_EXPORT QString globalRandomProvider()
Return the name of the global random number provider.
QCA_EXPORT QString arrayToBase64(const QByteArray &array)
Convert a byte array to printable base64 representation.
QCA_EXPORT Provider * findProvider(const QString &name)
Return the named provider, or 0 if not found.
QCA_EXPORT void setAppName(const QString &name)
Set the application name that will be used by SASL server mode.
QCA_EXPORT CertificateCollection systemStore()
Get system-wide root Certificate Authority (CA) certificates.
QCA_EXPORT int qcaVersion()
The current version of QCA.
QCA_EXPORT int qcaMinorVersion()
The current version of QCA.
QCA_EXPORT const char * qcaVersionStr()
The current version of QCA.
QCA_EXPORT int qcaPatchVersion()
The current version of QCA.
QCA_EXPORT int qcaMajorVersion()
The current version of QCA.
Header file for "support" classes used in QCA.
Header file for "tool" classes used in QCA.
Header file with QCA version.