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
24	/**
25	\file qca_core.h
26
27	Header file for core %QCA infrastructure
28
29	\note You should not use this header directly from an
30	application. You should just use <tt> \#include \<QtCrypto>
31	</tt> instead.
32	*/
33
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
47	/**
48	The current version of %QCA.
49
50	This is equivalent to ::QCA_VERSION, except it provides
51	a runtime check of the version of %QCA that is being used.
52	*/
53	QCA_EXPORT int qcaVersion();
54
55	/**
56	The current version of %QCA.
57
58	This is equivalent to ::QCA_VERSION_STR, except it provides
59	a runtime check of the version of %QCA that is being used.
60	*/
61	QCA_EXPORT const char *qcaVersionStr();
62
63	/**
64	The current version of %QCA.
65
66	This is equivalent to ::QCA_MAJOR_VERSION, except it provides
67	a runtime check of the version of %QCA that is being used.
68	*/
69	QCA_EXPORT int qcaMajorVersion();
70
71	/**
72	The current version of %QCA.
73
74	This is equivalent to ::QCA_MINOR_VERSION, except it provides
75	a runtime check of the version of %QCA that is being used.
76	*/
77	QCA_EXPORT int qcaMinorVersion();
78
79	/**
80	The current version of %QCA.
81
82	This is equivalent to ::QCA_PATCH_VERSION, except it provides
83	a runtime check of the version of %QCA that is being used.
84	*/
85	QCA_EXPORT int qcaPatchVersion();
86
87	/**
88	QCA - the Qt Cryptographic Architecture
89	*/
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
102	/**
103	Convenience representation for the plugin providers
104
105	You can get a list of providers using the providers()
106	function
107
108	\sa ProviderListIterator
109	\sa providers()
110	*/
111	typedef QList<Provider *> ProviderList;
112
113	/**
114	Mode settings for memory allocation
115
116	QCA can use secure memory, however most operating systems
117	restrict the amount of memory that can be pinned by user
118	applications, to prevent a denial-of-service attack.
119
120	QCA supports two approaches to getting memory - the mlock
121	method, which generally requires root (administrator) level
122	privileges, and the mmap method which is not as secure, but
123	which should be able to be used by any process.
124
125	\sa Initializer
126	*/
127	enum MemoryMode
128	{
129	Practical, ///< mlock and drop root if available, else mmap
130	Locking, ///< mlock and drop root
131	LockingKeepPrivileges ///< mlock, retaining root privileges
132	};
133
134	/**
135	Direction settings for symmetric algorithms
136
137	For some algorithms, it makes sense to have a "direction", such
138	as Cipher algorithms which can be used to encrypt or decrypt.
139	*/
140	enum Direction
141	{
142	Encode, ///< Operate in the "forward" direction; for example, encrypting
143	Decode ///< Operate in the "reverse" direction; for example, decrypting
144	};
145
146	/**
147	Initialise %QCA.
148	This call is not normally required, because it is cleaner
149	to use an Initializer.
150	*/
151	QCA_EXPORT void init();
152
153	/**
154	\overload
155
156	\param m the MemoryMode to use
157	\param prealloc the amount of memory in kilobytes to allocate
158	for secure storage
159	*/
160	QCA_EXPORT void init(MemoryMode m, int prealloc);
161
162	/**
163	Clean up routine
164
165	This routine cleans up %QCA, including memory allocations
166	This call is not normally required, because it is cleaner
167	to use an Initializer
168	*/
169	QCA_EXPORT void deinit();
170
171	/**
172	Test if secure storage memory is available
173
174	\return true if secure storage memory is available
175	*/
176	QCA_EXPORT bool haveSecureMemory();
177
178	/**
179	Test if secure random is available
180
181	Secure random is considered available if the global random
182	provider is not the default provider.
183
184	\return true if secure random is available
185	*/
186	QCA_EXPORT bool haveSecureRandom();
187
188	/**
189	Test if a capability (algorithm) is available.
190
191	Since capabilities are made available at runtime, you
192	should always check before using a capability the first
193	time, as shown below.
194	\code
195	QCA::init();
196	if(!QCA::isSupported("sha1"))
197	printf("SHA1 not supported!\n");
198	else
199	{
200	QString result = QCA::SHA1::hashToString(myString);
201	printf("sha1(\"%s\") = [%s]\n", myString.data(), qPrintable(result));
202	}
203	\endcode
204
205	\param features the name of the capability to test for
206	\param provider if specified, only check for the capability in that
207	specific provider. If not provided, or provided as an empty
208	string, then check for capabilities in all available providers
209	\return true if the capability is available, otherwise false
210
211	Note that you can test for a combination of capabilities,
212	using a comma delimited list:
213	\code
214	QCA::isSupported("sha1,md5"):
215	\endcode
216	which will return true if all of the capabilities listed
217	are present.
218	*/
219	QCA_EXPORT bool isSupported(const char *features, const QString &provider = QString());
220
221	/**
222	\overload
223
224	\param features a list of features to test for
225	\param provider if specified, only check for the capability in that
226	specific provider. If not provided, or provided as an empty
227	string, then check for capabilities in all available providers
228	*/
229	QCA_EXPORT bool isSupported(const QStringList &features, const QString &provider = QString());
230
231	/**
232	Generate a list of all the supported features in plugins,
233	and in built in capabilities
234
235	\return a list containing the names of the features
236
237	The following code writes a list of features to standard out
238	\code
239	QStringList capabilities;
240	capabilities = QCA::supportedFeatures();
241	std::cout << "Supported:" << capabilities.join(",") << std::endl;
242	\endcode
243	\sa isSupported(const char *features)
244	\sa isSupported(const QStringList &features)
245	\sa defaultFeatures()
246	*/
247	QCA_EXPORT QStringList supportedFeatures();
248
249	/**
250	Generate a list of the built in features. This differs from
251	supportedFeatures() in that it does not include features provided
252	by plugins.
253
254	\return a list containing the names of the features
255
256	The following code writes a list of features to standard out
257	\code
258	QStringList capabilities;
259	capabilities = QCA::defaultFeatures();
260	std::cout << "Default:" << capabilities.join(",") << std::endl;
261	\endcode
262
263	\sa isSupported
264	\sa supportedFeatures()
265	*/
266	QCA_EXPORT QStringList defaultFeatures();
267
268	/**
269	Add a provider to the current list of providers
270
271	This function allows you to add a provider to the
272	current plugin providers at a specified priority. If
273	a provider with the name already exists, this call fails.
274
275	QCA takes ownership of the provider.
276
277	\param p a pointer to a Provider object, which must be
278	set up.
279	\param priority the priority level to set the provider to
280	\return true if the provider is added, and false if the
281	provider is not added (failure)
282
283	\sa unloadProvider for unloading specified providers
284	\sa setProviderPriority for a description of the provider priority system
285	*/
286	QCA_EXPORT bool insertProvider(Provider *p, int priority = 0);
287
288	/**
289	Unload specified provider
290
291	The specified provider is removed from the list of providers
292	and deleted. If no provider with the name is found, this call fails.
293
294	\param name the name of the provider
295	\return true if the provider is unloaded, and false if the provider
296	cannot be found
297
298	\sa insertProvider for adding providers
299	*/
300	QCA_EXPORT bool unloadProvider(const QString &name);
301
302	/**
303	Change the priority of a specified provider
304
305	QCA supports a number of providers, and if a number of providers
306	support the same algorithm, it needs to choose between them. You
307	can do this at object instantiation time (by specifying the name
308	of the provider that should be used). Alternatively, you can provide a
309	relative priority level at an application level, using this call.
310
311	Priority is used at object instantiation time. The provider is selected
312	according to the following logic:
313	- if a particular provider is nominated, and that provider supports
314	the required algorithm, then the nominated provider is used
315	- if no provider is nominated, or it doesn't support the required
316	algorithm, then the provider with the lowest priority number will be used,
317	if that provider supports the algorithm.
318	- if the provider with the lowest priority number doesn't support
319	the required algorithm, the provider with the next lowest priority number
320	will be tried, and so on through to the provider with the largest priority
321	number
322	- if none of the plugin providers support the required algorithm, then
323	the default (built-in) provider will be tried.
324
325	\param name the name of the provider
326	\param priority the new priority of the provider. As a special case, if
327	you pass in -1, then this provider gets the same priority as the
328	the last provider that was added or had its priority set using this
329	call.
330
331	\sa providerPriority
332	*/
333	QCA_EXPORT void setProviderPriority(const QString &name, int priority);
334
335	/**
336	Return the priority of a specified provider
337
338	The name of the provider (eg "qca-ossl") is used to look up the
339	current priority associated with that provider. If the provider
340	is not found (or something else went wrong), -1 is returned.
341
342	\param name the name of the provider
343
344	\return the current priority level
345
346	\sa setProviderPriority for a description of the provider priority system
347	*/
348	QCA_EXPORT int providerPriority(const QString &name);
349
350	/**
351	Return a list of the current providers
352
353	The current plugin providers are provided as a list, which you
354	can iterate over using ProviderListIterator.
355
356	\sa ProviderList
357	\sa ProviderListIterator
358	*/
359	QCA_EXPORT ProviderList providers();
360
361	/**
362	Return the named provider, or 0 if not found
363
364	\param name the name of the provider to search for.
365	*/
366	QCA_EXPORT Provider *findProvider(const QString &name);
367
368	/**
369	Return the default provider
370	*/
371	QCA_EXPORT Provider *defaultProvider();
372
373	/**
374	Retrieve plugin paths. It consists of:
375	1. QCA_PLUGIN_PATH environment if set.
376	2. \c %QCoreApplication::libraryPaths() .
377	3. Directory where plugins were installed.
378
379	QCA_PLUGIN_PATH is paths list like PATH or QT_PLUGIN_PATH.
380	It uses system path separator. \";\" on Windows and \":\" on Unix.
381
382	This function was introduced in %QCA 2.1.
383	*/
384	QCA_EXPORT QStringList pluginPaths();
385
386	/**
387	Scan for new plugins
388	*/
389	QCA_EXPORT void scanForPlugins();
390
391	/**
392	Unload the current plugins
393	*/
394	QCA_EXPORT void unloadAllPlugins();
395
396	/**
397	Retrieve plugin diagnostic text
398	*/
399	QCA_EXPORT QString pluginDiagnosticText();
400
401	/**
402	Clear plugin diagnostic text
403	*/
404	QCA_EXPORT void clearPluginDiagnosticText();
405
406	/**
407	Add plugin diagnostic text
408
409	This function should only be called by providers.
410
411	\param text the diagnostic message to append
412	*/
413	QCA_EXPORT void appendPluginDiagnosticText(const QString &text);
414
415	/**
416	Set a global property
417
418	\param name the name of the property
419	\param value the value to set the property to
420
421	\sa getProperty
422	*/
423	QCA_EXPORT void setProperty(const QString &name, const QVariant &value);
424
425	/**
426	Retrieve a global property
427
428	\param name the name of the property to look up
429
430	\sa setProperty
431	*/
432	QCA_EXPORT QVariant getProperty(const QString &name);
433
434	/**
435	Set provider configuration
436
437	Allowed value types: QString, int, bool
438
439	\param name the name of the provider to set the configuration to
440	\param config the configuration
441	*/
442	QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config);
443
444	/**
445	Retrieve provider configuration
446
447	\param name the name of the provider to retrieve the configuration of
448	*/
449	QCA_EXPORT QVariantMap getProviderConfig(const QString &name);
450
451	/**
452	Save provider configuration to persistent storage
453
454	\param name the name of the provider to have its configuration saved
455	*/
456	QCA_EXPORT void saveProviderConfig(const QString &name);
457
458	/**
459	Return the name of the global random number provider
460	*/
461	QCA_EXPORT QString globalRandomProvider();
462
463	/**
464	Change the global random number provider
465
466	The Random capabilities of %QCA are provided as part of the
467	built in capabilities, however the generator can be changed
468	if required.
469
470	\param provider the name of the provider to use as the global random
471	provider.
472	*/
473	QCA_EXPORT void setGlobalRandomProvider(const QString &provider);
474
475	/**
476	Return a reference to the %QCA Logger, which is used for diagnostics
477	and error recording.
478
479	The system Logger is automatically created for you on start.
480	*/
481	QCA_EXPORT Logger *logger();
482
483	/**
484	Log a text message. This is an efficient function
485	to avoid overhead of argument executions when log level
486	blocks the message.
487
488	\param message the text to log
489	\param severity the type of information to log
490
491	\note This is a macro, so arguments may or may not be evaluated.
492	*/
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
502	/**
503	Log a binary message. This is an efficient function
504	to avoid overhead of argument executions when log level
505	blocks the message.
506
507	\param blob the blob to log
508	\param severity the type of information to log
509
510	\note This is a macro, so arguments may or may not be evaluated.
511	*/
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
521	/**
522	Test if QCA can access the root CA certificates
523
524	If root certificates are available, this function returns true,
525	otherwise it returns false.
526
527	\sa systemStore
528	*/
529	QCA_EXPORT bool haveSystemStore();
530
531	/**
532	Get system-wide root Certificate Authority (CA) certificates
533
534	Many operating systems (or distributions, on Linux-type systems)
535	come with some trusted certificates. Typically, these include
536	the root certificates for major Certificate Authorities (for
537	example, Verisign, Comodo) and some additional certificates that
538	are used for system updates. They are provided in different ways
539	for different systems.
540
541	This function provides an common way to access the system
542	certificates. There are other ways to access certificates - see
543	the various I/O methods (such as fromDER() and fromPEM())
544	in the Certificate and CertificateCollection classes.
545
546	\note Availability of the system certificates depends on how
547	%QCA was built. You can test whether the system certificates
548	are available using the haveSystemStore() function.
549
550	*/
551	QCA_EXPORT CertificateCollection systemStore();
552
553	/**
554	Get the application name that will be used by SASL server mode
555
556	The application name is used by SASL in server mode, as some systems might
557	have different security policies depending on the app.
558	The default application name is 'qca'
559	*/
560	QCA_EXPORT QString appName();
561
562	/**
563	Set the application name that will be used by SASL server mode
564
565	The application name is used by SASL in server mode, as some systems might
566	have different security policies depending on the app. This should be set
567	before using SASL objects, and it cannot be changed later.
568
569	\param name the name string to use for SASL server mode
570	*/
571	QCA_EXPORT void setAppName(const QString &name);
572
573	/**
574	Convert a byte array to printable hexadecimal
575	representation.
576
577	This is a convenience function to convert an arbitrary
578	QByteArray to a printable representation.
579
580	\code
581	QByteArray test(10);
582	test.fill('a');
583	// 0x61 is 'a' in ASCII
584	if (QString("61616161616161616161") == QCA::arrayToHex(test) )
585	{
586	printf ("arrayToHex passed\n");
587	}
588	\endcode
589
590	\param array the array to be converted
591	\return a printable representation
592	*/
593	QCA_EXPORT QString arrayToHex(const QByteArray &array);
594
595	/**
596	Convert a QString containing a hexadecimal representation
597	of a byte array into a QByteArray
598
599	This is a convenience function to convert a printable
600	representation into a QByteArray - effectively the inverse
601	of QCA::arrayToHex.
602
603	\code
604	QCA::init();
605	QByteArray test(10);
606
607	test.fill('b'); // 0x62 in hexadecimal
608	test[7] = 0x00; // can handle strings with nulls
609
610	if (QCA::hexToArray(QString("62626262626262006262") ) == test )
611	{
612	printf ("hexToArray passed\n");
613	}
614	\endcode
615
616	\param hexString the string containing a printable
617	representation to be converted
618	\return the equivalent QByteArray
619	*/
620	QCA_EXPORT QByteArray hexToArray(const QString &hexString);
621
622	/**
623	Convert a byte array to printable base64
624	representation.
625
626	This is a convenience function to convert an arbitrary
627	QByteArray to a printable representation.
628
629	\param array the array to be converted
630	\return a printable representation
631	*/
632	QCA_EXPORT QString arrayToBase64(const QByteArray &array);
633
634	/**
635	Convert a QString containing a base64 representation
636	of a byte array into a QByteArray
637
638	This is a convenience function to convert a printable
639	representation into a QByteArray - effectively the inverse
640	of QCA::arrayToBase64.
641
642	\param base64String the string containing a printable
643	representation to be converted
644	\return the equivalent QByteArray
645	*/
646	QCA_EXPORT QByteArray base64ToArray(const QString &base64String);
647
648	/**
649	\class Initializer qca_core.h QtCrypto
650
651	Convenience method for initialising and cleaning up %QCA
652
653	To ensure that QCA is properly initialised and cleaned up,
654	it is convenient to create an Initializer object, and let it
655	go out of scope at the end of %QCA usage.
656
657	\ingroup UserAPI
658	*/
659	class QCA_EXPORT Initializer
660	{
661	public:
662	/**
663	Standard constructor
664
665	\param m the MemoryMode to use for secure memory
666	\param prealloc the amount of secure memory to pre-allocate,
667	in units of 1024 bytes (1K).
668	*/
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
676	/**
677	\class KeyLength qca_core.h QtCrypto
678
679	Simple container for acceptable key lengths
680
681	The KeyLength specifies the minimum and maximum byte sizes
682	allowed for a key, as well as a "multiple" which the key
683	size must evenly divide into.
684
685	As an example, if the key can be 4, 8 or 12 bytes, you can
686	express this as
687	\code
688	KeyLength keyLen( 4, 12, 4 );
689	\endcode
690
691	If you want to express a KeyLength that takes any number
692	of bytes (including zero), you may want to use
693	\code
694	#include<limits>
695	KeyLength( 0, std::numeric_limits<int>::max(), 1 );
696	\endcode
697
698	\ingroup UserAPI
699	*/
700	class QCA_EXPORT KeyLength
701	{
702	public:
703	/**
704	Construct a %KeyLength object
705
706	\param min the minimum length of the key, in bytes
707	\param max the maximum length of the key, in bytes
708	\param multiple the number of bytes that the key must be a
709	multiple of.
710	*/
711	KeyLength(int min, int max, int multiple)
712	: _min(min)
713	, _max(max)
714	, _multiple(multiple)
715	{
716	}
717
718	/**
719	Obtain the minimum length for the key, in bytes
720	*/
721	int minimum() const
722	{
723	return _min;
724	}
725
726	/**
727	Obtain the maximum length for the key, in bytes
728	*/
729	int maximum() const
730	{
731	return _max;
732	}
733
734	/**
735	Return the number of bytes that the key must be a multiple of
736
737	If this is one, then anything between minimum and maximum (inclusive)
738	is acceptable.
739	*/
740	int multiple() const
741	{
742	return _multiple;
743	}
744
745	private:
746	const int _min, _max, _multiple;
747	};
748
749	/**
750	\class Provider qca_core.h QtCrypto
751
752	Algorithm provider
753
754	Provider represents a plugin provider (or as a special case, the
755	built-in provider). This is the class you need to inherit
756	from to create your own plugin. You don't normally need to
757	worry about this class if you are just using existing
758	QCA capabilities and plugins, however there is nothing stopping
759	you from using it to obtain information about specific plugins,
760	as shown in the example below.
761
762	\ingroup ProviderAPI
763	*/
764	class QCA_EXPORT Provider
765	{
766	public:
767	virtual ~Provider();
768
769	class Context;
770
771	/**
772	Initialisation routine
773
774	This routine will be called when your plugin
775	is loaded, so this is a good place to do any
776	one-off initialisation tasks. If you don't need
777	any initialisation, just implement it as an empty
778	routine.
779	*/
780	virtual void init();
781
782	/**
783	Deinitialisation routine
784
785	This routine will be called just before provider destruction.
786	Notably, during QCA shutdown, deinit() will be called on all
787	providers before any of the providers are destructed. Use this
788	opportunity to free any resources that may be used by other
789	providers.
790	*/
791	virtual void deinit();
792
793	/**
794	Version number of the plugin
795
796	The format is the same as QCA itself. Version 1.2.3 would be
797	represented as 0x010203.
798
799	The default returns 0 (version 0.0.0).
800	*/
801	virtual int version() const;
802
803	/**
804	Target QCA version for the provider.
805
806	This is used to verify compatibility between the
807	provider and QCA. For a provider to be used, it
808	must supply major and minor version numbers here that are
809	less-than or equal to the actual QCA version (the patch
810	version number is ignored). This means an older
811	provider may be used with a newer QCA, but a newer
812	provider cannot be used with an older QCA.
813	*/
814	virtual int qcaVersion() const = 0;
815
816	/**
817	The name of the provider.
818
819	Typically you just return a string containing a
820	convenient name.
821
822	\code
823	QString name() const
824	{
825	return "qca-myplugin";
826	}
827	\endcode
828
829	\note The name is used to tell if a provider is
830	already loaded, so you need to make sure it is
831	unique amongst the various plugins.
832	*/
833	virtual QString name() const = 0;
834
835	/**
836	The capabilities (algorithms) of the provider.
837
838	Typically you just return a fixed QStringList:
839	\code
840	QStringList features() const
841	{
842	QStringList list;
843	list += "sha1";
844	list += "sha256";
845	list += "hmac(sha1)";
846	return list;
847	}
848	\endcode
849	*/
850	virtual QStringList features() const = 0;
851
852	/**
853	Optional credit text for the provider.
854
855	You might display this information in a credits or
856	"About" dialog. Returns an empty string if the
857	provider has no credit text. Only report credit text
858	when absolutely required (for example, an "advertisement
859	clause" related to licensing). Do not use it for
860	reporting general author information.
861	*/
862	virtual QString credit() const;
863
864	/**
865	Routine to create a plugin context
866
867	You need to return a pointer to an algorithm
868	Context that corresponds with the algorithm
869	name specified.
870
871	\param type the name of the algorithm required
872
873	\code
874	Context *createContext(const QString &type)
875	{
876	if ( type == "sha1" )
877	return new SHA1Context( this );
878	else if ( type == "sha256" )
879	return new SHA0256Context( this );
880	else if ( type == "hmac(sha1)" )
881	return new HMACSHA1Context( this );
882	else
883	return 0;
884	}
885	\endcode
886
887	Naturally you also need to implement
888	the specified Context subclasses as well.
889	*/
890	virtual Context *createContext(const QString &type) = 0;
891
892	/**
893	Method to set up the default configuration options.
894
895	If your provider needs some configuration options,
896	this method allows you to establish default options.
897	The user can then change the configuration options
898	as required, and set them using configChanged().
899
900	You need to return a QVariantMap that has configuration
901	options as the keys, and the default configuration
902	as the values, as shown below:
903	\code
904	QVariantMap defaultConfig() const
905	{
906	QVariantMap myConfig;
907	myConfig[ "firstOption" ] = QString("firstOptionValue");
908	myConfig[ "secondOption" ] = true;
909	myConfig[ "thirdOpt" ] = 1243;
910	return myConfig;
911	}
912	\endcode
913
914	\sa configChanged for how to set the configuration;
915	*/
916	virtual QVariantMap defaultConfig() const;
917
918	/**
919	Method to set the configuration options.
920
921	If your provider supports configuration options, you
922	will be advised of user changes to the configuration
923	when this method is called.
924
925	\param config the new configuration to be used by the provider
926	*/
927	virtual void configChanged(const QVariantMap &config);
928	};
929
930	/**
931	\class QCA::Provider::Context qca_core.h QtCrypto
932
933	Internal context class used for the plugin
934
935	\internal
936
937	\ingroup ProviderAPI
938	*/
939	class QCA_EXPORT Provider::Context : public QObject
940	{
941	Q_OBJECT
942	public:
943	~Context() override;
944
945	/**
946	The Provider associated with this Context
947	*/
948	Provider *provider() const;
949
950	/**
951	The type of context, as passed to the constructor
952	*/
953	QString type() const;
954
955	/**
956	Create a duplicate of this Context
957	*/
958	virtual Context *clone() const = 0;
959
960	/**
961	Test if two Contexts have the same Provider
962
963	\param c pointer to the Context to compare to
964
965	\return true if the argument and this Context
966	have the same provider.
967	*/
968	bool sameProvider(const Context *c) const;
969
970	protected:
971	/**
972	Standard constructor
973
974	\param parent the parent provider for this
975	context
976	\param type the name of the provider context type
977	*/
978	Context(Provider *parent, const QString &type);
979
980	/**
981	Copy constructor
982
983	\param from the Context to copy from
984	*/
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
995	/**
996	\class BasicContext qca_core.h QtCrypto
997
998	Base class to use for primitive provider contexts
999
1000	\internal
1001
1002	This class inherits Provider::Context and calls moveToThread(0) on
1003	itself, thereby disabling the event properties of the underlying
1004	QObject. Context types that need to be a QObject should inherit from
1005	Provider::Context, those that don't should inherit from BasicContext.
1006
1007	\ingroup ProviderAPI
1008	*/
1009	class QCA_EXPORT BasicContext : public Provider::Context
1010	{
1011	Q_OBJECT
1012	public:
1013	~BasicContext() override;
1014
1015	protected:
1016	/**
1017	Standard constructor
1018
1019	\param parent the parent provider for this
1020	context
1021	\param type the name of the provider context type
1022	*/
1023	BasicContext(Provider *parent, const QString &type);
1024
1025	/**
1026	Copy constructor
1027
1028	\param from the Context to copy from
1029	*/
1030	BasicContext(const BasicContext &from);
1031
1032	private:
1033	// disable assignment
1034	BasicContext &operator=(const BasicContext &from);
1035	};
1036
1037	/**
1038	\class BufferedComputation qca_core.h QtCrypto
1039
1040	General superclass for buffered computation algorithms
1041
1042	A buffered computation is characterised by having the
1043	algorithm take data in an incremental way, then having
1044	the results delivered at the end. Conceptually, the
1045	algorithm has some internal state that is modified
1046	when you call update() and returned when you call
1047	final().
1048
1049	\ingroup UserAPI
1050	*/
1051	class QCA_EXPORT BufferedComputation
1052	{
1053	public:
1054	virtual ~BufferedComputation();
1055
1056	/**
1057	Reset the internal state
1058	*/
1059	virtual void clear() = 0;
1060
1061	/**
1062	Update the internal state with a byte array
1063
1064	\param a the byte array of data that is to
1065	be used to update the internal state.
1066	*/
1067	virtual void update(const MemoryRegion &a) = 0;
1068
1069	/**
1070	Complete the algorithm and return the internal state
1071	*/
1072	virtual MemoryRegion final() = 0;
1073
1074	/**
1075	Perform an "all in one" update, returning
1076	the result. This is appropriate if you
1077	have all the data in one array - just
1078	call process on that array, and you will
1079	get back the results of the computation.
1080
1081	\note This will invalidate any previous
1082	computation using this object.
1083
1084	\param a the data to process.
1085	*/
1086	MemoryRegion process(const MemoryRegion &a);
1087	};
1088
1089	/**
1090	\class Filter qca_core.h QtCrypto
1091
1092	General superclass for filtering transformation algorithms
1093
1094	A filtering computation is characterised by having the
1095	algorithm take input data in an incremental way, with results
1096	delivered for each input, or block of input. Some internal
1097	state may be managed, with the transformation completed
1098	when final() is called.
1099
1100	If this seems a big vague, then you might try deriving
1101	your class from a subclass with stronger semantics, or if your
1102	update() function is always returning null results, and
1103	everything comes out at final(), try BufferedComputation.
1104
1105	\ingroup UserAPI
1106	*/
1107	class QCA_EXPORT Filter
1108	{
1109	public:
1110	virtual ~Filter();
1111
1112	/**
1113	Reset the internal state
1114	*/
1115	virtual void clear() = 0;
1116
1117	/**
1118	Process more data, returning the corresponding
1119	filtered version of the data.
1120
1121	\param a the array containing data to process
1122	*/
1123	virtual MemoryRegion update(const MemoryRegion &a) = 0;
1124
1125	/**
1126	Complete the algorithm, returning any
1127	additional results.
1128	*/
1129	virtual MemoryRegion final() = 0;
1130
1131	/**
1132	Test if an update() or final() call succeeded.
1133
1134	\return true if the previous call succeeded
1135	*/
1136	virtual bool ok() const = 0;
1137
1138	/**
1139	Perform an "all in one" update, returning
1140	the result. This is appropriate if you
1141	have all the data in one array - just
1142	call process on that array, and you will
1143	get back the results of the computation.
1144
1145	\note This will invalidate any previous
1146	computation using this object.
1147
1148	\param a the data to process in this step
1149	*/
1150	MemoryRegion process(const MemoryRegion &a);
1151	};
1152
1153	/**
1154	\class Algorithm qca_core.h QtCrypto
1155
1156	General superclass for an algorithm.
1157
1158	This is a fairly abstract class, mainly used for
1159	implementing the backend "provider" interface.
1160
1161	\ingroup UserAPI
1162	*/
1163	class QCA_EXPORT Algorithm
1164	{
1165	public:
1166	/**
1167	Standard copy constructor
1168
1169	\param from the Algorithm to copy from
1170	*/
1171	Algorithm(const Algorithm &from);
1172
1173	virtual ~Algorithm();
1174
1175	/**
1176	Assignment operator
1177
1178	\param from the Algorithm to copy state from
1179	*/
1180	Algorithm &operator=(const Algorithm &from);
1181
1182	/**
1183	The name of the algorithm type.
1184	*/
1185	QString type() const;
1186
1187	/**
1188	The name of the provider
1189
1190	Each algorithm is implemented by a provider. This
1191	allows you to figure out which provider is associated
1192	*/
1193	Provider *provider() const;
1194
1195	// Note: The next five functions are not public!
1196
1197	/**
1198	\internal
1199
1200	The context associated with this algorithm
1201	*/
1202	Provider::Context *context();
1203
1204	/**
1205	\internal
1206
1207	The context associated with this algorithm
1208	*/
1209	const Provider::Context *context() const;
1210
1211	/**
1212	\internal
1213
1214	Set the Provider for this algorithm
1215
1216	\param c the context for the Provider to use
1217	*/
1218	void change(Provider::Context *c);
1219
1220	/**
1221	\internal
1222
1223	\overload
1224
1225	\param type the name of the algorithm to use
1226	\param provider the name of the preferred provider
1227	*/
1228	void change(const QString &type, const QString &provider);
1229
1230	/**
1231	\internal
1232
1233	Take the Provider from this algorithm
1234	*/
1235	Provider::Context *takeContext();
1236
1237	protected:
1238	/**
1239	Constructor for empty algorithm
1240	*/
1241	Algorithm();
1242
1243	/**
1244	Constructor of a particular algorithm.
1245
1246	\param type the algorithm to construct
1247	\param provider the name of a particular Provider
1248	*/
1249	Algorithm(const QString &type, const QString &provider);
1250
1251	private:
1252	class Private;
1253	QSharedDataPointer<Private> d;
1254	};
1255
1256	/**
1257	\class SymmetricKey qca_core.h QtCrypto
1258
1259	Container for keys for symmetric encryption algorithms.
1260
1261	\ingroup UserAPI
1262	*/
1263	class QCA_EXPORT SymmetricKey : public SecureArray
1264	{
1265	public:
1266	/**
1267	Construct an empty (zero length) key
1268	*/
1269	SymmetricKey();
1270
1271	/**
1272	Construct an key of specified size, with random contents
1273
1274	This is intended to be used as a random session key.
1275
1276	\param size the number of bytes for the key
1277	*/
1278	SymmetricKey(int size);
1279
1280	/**
1281	Construct a key from a provided byte array
1282
1283	\param a the byte array to copy
1284	*/
1285	SymmetricKey(const SecureArray &a);
1286
1287	/**
1288	Construct a key from a provided byte array
1289
1290	\param a the byte array to copy
1291	*/
1292	SymmetricKey(const QByteArray &a);
1293
1294	/**
1295	Test for weak DES keys
1296
1297	\return true if the key is a weak key for DES
1298	*/
1299	bool isWeakDESKey();
1300	};
1301
1302	/**
1303	\class InitializationVector qca_core.h QtCrypto
1304
1305	Container for initialisation vectors and nonces
1306
1307	\ingroup UserAPI
1308	*/
1309	class QCA_EXPORT InitializationVector : public SecureArray
1310	{
1311	public:
1312	/**
1313	Construct an empty (zero length) initialization vector
1314	*/
1315	InitializationVector();
1316
1317	/**
1318	Construct an initialization vector of the specified size
1319
1320	\param size the length of the initialization vector, in bytes
1321	*/
1322	InitializationVector(int size);
1323
1324	/**
1325	Construct an initialization vector from a provided byte array
1326
1327	\param a the byte array to copy
1328	*/
1329	InitializationVector(const SecureArray &a);
1330
1331	/**
1332	Construct an initialization vector from a provided byte array
1333
1334	\param a the byte array to copy
1335	*/
1336	InitializationVector(const QByteArray &a);
1337	};
1338
1339	/**
1340	\class AuthTag qca_core.h QtCrypto
1341
1342	Container for authentication tag
1343
1344	\ingroup UserAPI
1345	*/
1346	class QCA_EXPORT AuthTag : public SecureArray
1347	{
1348	public:
1349	/**
1350	Construct an empty authentication tag
1351	*/
1352	AuthTag();
1353
1354	/**
1355	Construct an empty authentication tag of the specified size
1356
1357	\param size the length of the authentication tag, in bytes
1358	*/
1359	AuthTag(int size);
1360
1361	/**
1362	Construct an authentication tag from a provided byte array
1363
1364	\param a the byte array to copy
1365	*/
1366	AuthTag(const SecureArray &a);
1367
1368	/**
1369	Construct an authentication tag from a provided byte array
1370
1371	\param a the byte array to copy
1372	*/
1373	AuthTag(const QByteArray &a);
1374	};
1375
1376	/**
1377	\class Event qca_core.h QtCrypto
1378
1379	An asynchronous event
1380
1381	Events are produced in response to the library's need for some user
1382	intervention, such as entering a pin or password, or inserting a
1383	cryptographic token.
1384
1385	Event is an abstraction, so you can handle this need in a way that makes
1386	sense for your application.
1387
1388	\ingroup UserAPI
1389	*/
1390	class QCA_EXPORT Event
1391	{
1392	public:
1393	/**
1394	%Type of event
1395
1396	\sa type()
1397	*/
1398	enum Type
1399	{
1400	Password, ///< Asking for a password, PIN or passphrase.
1401	Token ///< Asking for a token
1402	};
1403
1404	/**
1405	%Source of the event
1406
1407	Events are associated with access to a KeyStore, or access to
1408	a file (or bytearray/stream or equivalent). This tells you the
1409	type of source that caused the Event.
1410
1411	\sa source()
1412	\sa fileName() for the name, if source is Event::Data
1413	\sa keyStoreInfo() and keyStoreEntry() for the keystore and entry,
1414	if the source is Event::KeyStore
1415	*/
1416	enum Source
1417	{
1418	KeyStore, ///< KeyStore generated the event
1419	Data ///< File or bytearray generated the event
1420	};
1421
1422	/**
1423	password variation
1424
1425	If the Type of Event is Password, PasswordStyle tells you whether
1426	it is a PIN, passphrase or password.
1427
1428	\sa passwordStyle()
1429	*/
1430	enum PasswordStyle
1431	{
1432	StylePassword, ///< User should be prompted for a "Password"
1433	StylePassphrase, ///< User should be prompted for a "Passphrase"
1434	StylePIN ///< User should be prompted for a "PIN"
1435	};
1436
1437	/**
1438	Constructor
1439	*/
1440	Event();
1441
1442	/**
1443	Copy constructor
1444
1445	\param from the Event to copy from
1446	*/
1447	Event(const Event &from);
1448
1449	/**
1450	Destructor
1451	*/
1452	~Event();
1453
1454	/**
1455	Assignment operator
1456
1457	\param from the Event to copy from
1458	*/
1459	Event &operator=(const Event &from);
1460
1461	/**
1462	test if this event has been setup correctly
1463	*/
1464	bool isNull() const;
1465
1466	/**
1467	the Type of this event
1468	*/
1469	Type type() const;
1470
1471	/**
1472	the Source of this event
1473	*/
1474	Source source() const;
1475
1476	/**
1477	the style of password required.
1478
1479	This is not meaningful unless the Type is Event::Password.
1480
1481	\sa PasswordStyle
1482	*/
1483	PasswordStyle passwordStyle() const;
1484
1485	/**
1486	The info of the KeyStore associated with this event
1487
1488	This is not meaningful unless the Source is KeyStore.
1489	*/
1490	KeyStoreInfo keyStoreInfo() const;
1491
1492	/**
1493	The KeyStoreEntry associated with this event
1494
1495	This is not meaningful unless the Source is KeyStore.
1496	*/
1497	KeyStoreEntry keyStoreEntry() const;
1498
1499	/**
1500	Name or other identifier for the file or byte array
1501	associated with this event.
1502
1503	This is not meaningful unless the Source is Data.
1504	*/
1505	QString fileName() const;
1506
1507	/**
1508	opaque data
1509	*/
1510	void *ptr() const;
1511
1512	/**
1513	Set the values for this Event
1514
1515	This creates a Password type event, for a keystore.
1516
1517	\param pstyle the style of information required (e.g. PIN,
1518	password or passphrase)
1519	\param keyStoreInfo info about the keystore that the information
1520	is required for
1521	\param keyStoreEntry the entry in the keystore that the
1522	information is required for
1523	\param ptr opaque data
1524	*/
1525	void setPasswordKeyStore(PasswordStyle pstyle,
1526	const KeyStoreInfo &keyStoreInfo,
1527	const KeyStoreEntry &keyStoreEntry,
1528	void *ptr);
1529
1530	/**
1531	Set the values for this Event
1532
1533	This creates a Password type event, for a file.
1534
1535	\param pstyle the style of information required (e.g. PIN,
1536	password or passphrase)
1537	\param fileName the name of the file (or other identifier) that
1538	the information is required for
1539	\param ptr opaque data
1540	*/
1541	void setPasswordData(PasswordStyle pstyle, const QString &fileName, void *ptr);
1542
1543	/**
1544	Set the values for this Event
1545
1546	This creates a Token type event.
1547
1548	\param keyStoreInfo info about the keystore that the token is
1549	required for
1550	\param keyStoreEntry the entry in the keystore that the token is
1551	required for
1552	\param ptr opaque data
1553	*/
1554	void setToken(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1555
1556	private:
1557	class Private;
1558	QSharedDataPointer<Private> d;
1559	};
1560
1561	/**
1562	\class EventHandler qca_core.h QtCrypto
1563
1564	Interface class for password / passphrase / PIN and token handlers
1565
1566	This class is used on client side applications to handle
1567	the provision of passwords, passphrases and PINs by users, and
1568	to indicate that tokens have been correctly inserted.
1569
1570	The concept behind this class is that the library can raise
1571	events (typically using PasswordAsker or TokenAsker), which
1572	may (or may not) be handled by the application using a
1573	handler object (that has-a EventHandler, or possibly is-a
1574	EventHandler) that is connected to the eventReady() signal.
1575
1576	\ingroup UserAPI
1577	*/
1578	class QCA_EXPORT EventHandler : public QObject
1579	{
1580	Q_OBJECT
1581	public:
1582	/**
1583	Constructor
1584
1585	\param parent the parent object for this object
1586	*/
1587	EventHandler(QObject *parent = nullptr);
1588	~EventHandler() override;
1589
1590	/**
1591	mandatory function to call after connecting the
1592	signal to a slot in your application specific password
1593	/ passphrase / PIN or token handler
1594	*/
1595	void start();
1596
1597	/**
1598	function to call to return the user provided
1599	password, passphrase or PIN.
1600
1601	\param id the id corresponding to the password request
1602	\param password the user-provided password, passphrase or PIN.
1603
1604	\note the id parameter is the same as that provided in the
1605	eventReady() signal.
1606	*/
1607	void submitPassword(int id, const SecureArray &password);
1608
1609	/**
1610	function to call to indicate that the token has been inserted
1611	by the user.
1612
1613	\param id the id corresponding to the password request
1614
1615	\note the id parameter is the same as that provided in the
1616	eventReady() signal.
1617	*/
1618	void tokenOkay(int id);
1619
1620	/**
1621	function to call to indicate that the user declined to
1622	provide a password, passphrase, PIN or token.
1623
1624	\param id the id corresponding to the password request
1625
1626	\note the id parameter is the same as that provided in the
1627	eventReady() signal.
1628	*/
1629	void reject(int id);
1630
1631	Q_SIGNALS:
1632	/**
1633	signal emitted when an Event requires attention.
1634
1635	You typically need to connect this signal to
1636	a compatible slot in your callback handler
1637
1638	\param id the identification number for the event
1639	\param context information about the type of response required
1640	*/
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
1651	/**
1652	\class PasswordAsker qca_core.h QtCrypto
1653
1654	User password / passphrase / PIN handler
1655
1656	This class is used to obtain a password from a user.
1657
1658	\ingroup UserAPI
1659	*/
1660	class QCA_EXPORT PasswordAsker : public QObject
1661	{
1662	Q_OBJECT
1663	public:
1664	/**
1665	Construct a new asker
1666
1667	\param parent the parent object for this QObject
1668	*/
1669	PasswordAsker(QObject *parent = nullptr);
1670	~PasswordAsker() override;
1671
1672	/**
1673	queue a password / passphrase request associated with a key store
1674
1675	\param pstyle the type of information required (e.g. PIN,
1676	passphrase or password)
1677	\param keyStoreInfo info of the key store that the information is
1678	required for
1679	\param keyStoreEntry the item in the key store that the
1680	information is required for (if applicable)
1681	\param ptr opaque data
1682	*/
1683	void
1684	ask(Event::PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1685
1686	/**
1687	queue a password / passphrase request associated with a file
1688
1689	\param pstyle the type of information required (e.g. PIN,
1690	passphrase or password)
1691	\param fileName the name of the file that the information is
1692	required for
1693	\param ptr opaque data
1694	*/
1695	void ask(Event::PasswordStyle pstyle, const QString &fileName, void *ptr);
1696
1697	/**
1698	Cancel the pending password / passphrase request
1699	*/
1700	void cancel();
1701
1702	/**
1703	Block until the password / passphrase request is
1704	completed
1705
1706	You can use the responseReady signal instead of
1707	blocking, if appropriate.
1708	*/
1709	void waitForResponse();
1710
1711	/**
1712	Determine whether the password / passphrase was accepted or not
1713
1714	In this context, returning true is indicative of the user clicking
1715	"Ok" or equivalent; and returning false indicates that either the
1716	user clicked "Cancel" or equivalent, or that the cancel() function
1717	was called, or that the request is still pending.
1718	*/
1719	bool accepted() const;
1720
1721	/**
1722	The password / passphrase / PIN provided by the user in response
1723	to the asker request. This may be empty.
1724	*/
1725	SecureArray password() const;
1726
1727	Q_SIGNALS:
1728	/**
1729	Emitted when the asker process has been completed.
1730
1731	You should check whether the user accepted() the response
1732	prior to relying on the password().
1733	*/
1734	void responseReady();
1735
1736	private:
1737	Q_DISABLE_COPY(PasswordAsker)
1738
1739	class Private;
1740	friend class Private;
1741	Private *d;
1742	};
1743
1744	/**
1745	\class TokenAsker qca_core.h QtCrypto
1746
1747	User token handler
1748
1749	This class is used to request the user to insert a token.
1750
1751	\ingroup UserAPI
1752	*/
1753	class QCA_EXPORT TokenAsker : public QObject
1754	{
1755	Q_OBJECT
1756	public:
1757	/**
1758	Construct a new asker
1759
1760	\param parent the parent object for this QObject
1761	*/
1762	TokenAsker(QObject *parent = nullptr);
1763	~TokenAsker() override;
1764
1765	/**
1766	queue a token request associated with a key store
1767
1768	\param keyStoreInfo info of the key store that the information is
1769	required for
1770	\param keyStoreEntry the item in the key store that the
1771	information is required for (if applicable)
1772	\param ptr opaque data
1773	*/
1774	void ask(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr);
1775
1776	/**
1777	Cancel the pending password / passphrase request
1778	*/
1779	void cancel();
1780
1781	/**
1782	Block until the token request is completed
1783
1784	You can use the responseReady signal instead of
1785	blocking, if appropriate.
1786	*/
1787	void waitForResponse();
1788
1789	/**
1790	Test if the token request was accepted or not.
1791
1792	\return true if the token request was accepted
1793	*/
1794	bool accepted() const;
1795
1796	Q_SIGNALS:
1797	/**
1798	Emitted when the asker process has been completed.
1799
1800	You should check whether the user accepted() the response
1801	prior to relying on token being present.
1802	*/
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
1816