1	/*
2	* qcaprovider.h - QCA Plugin API
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
23	/**
24	\file qcaprovider.h
25
26	Header file for provider implementation classes (plugins)
27
28	\note You should not use this header directly from an
29	application. You should just use <tt> \#include \<QtCrypto>
30	</tt> instead.
31	*/
32
33	#ifndef QCAPROVIDER_H
34	#define QCAPROVIDER_H
35
36	#include "qca_basic.h"
37	#include "qca_cert.h"
38	#include "qca_core.h"
39	#include "qca_keystore.h"
40	#include "qca_publickey.h"
41	#include "qca_securelayer.h"
42	#include "qca_securemessage.h"
43
44	#include <limits>
45
46	#ifndef DOXYGEN_NO_PROVIDER_API
47
48	/**
49	\defgroup ProviderAPI QCA provider API
50
51	This group of classes is not normally needed
52	by application writers, but can be used to extend QCA if
53	required
54	*/
55
56	/**
57	\class QCAPlugin qcaprovider.h QtCrypto
58
59	Provider plugin base class
60
61	QCA loads cryptographic provider plugins with QPluginLoader. The QObject
62	obtained when loading the plugin must implement the QCAPlugin interface.
63	This is done by inheriting QCAPlugin, and including
64	Q_INTERFACES(QCAPlugin) in your class declaration.
65
66	For example:
67	\code
68	class MyPlugin : public QObject, public QCAPlugin
69	{
70	Q_OBJECT
71	Q_INTERFACES(QCAPlugin)
72	public:
73	virtual Provider *createProvider() { ... }
74	};
75	\endcode
76
77	There is only one function to reimplement, called createProvider(). This
78	function should return a newly allocated Provider instance.
79
80	\ingroup ProviderAPI
81	*/
82	class QCA_EXPORT QCAPlugin
83	{
84	public:
85	/**
86	Destructs the object
87	*/
88	virtual ~QCAPlugin()
89	{
90	}
91
92	/**
93	Returns a newly allocated Provider instance.
94	*/
95	virtual QCA::Provider *createProvider() = 0;
96	};
97
98	Q_DECLARE_INTERFACE(QCAPlugin, "com.affinix.qca.Plugin/1.0")
99
100	namespace QCA {
101
102	/**
103	\class InfoContext qcaprovider.h QtCrypto
104
105	Extended provider information
106
107	\note This class is part of the provider plugin interface and should not
108	be used directly by applications.
109
110	\ingroup ProviderAPI
111	*/
112	class QCA_EXPORT InfoContext : public BasicContext
113	{
114	Q_OBJECT
115	public:
116	/**
117	Standard constructor
118
119	\param p the provider associated with this context
120	*/
121	InfoContext(Provider *p)
122	: BasicContext(p, QStringLiteral("info"))
123	{
124	}
125
126	/**
127	The hash algorithms supported by the provider
128	*/
129	virtual QStringList supportedHashTypes() const;
130
131	/**
132	The cipher algorithms supported by the provider
133	*/
134	virtual QStringList supportedCipherTypes() const;
135
136	/**
137	The mac algorithms supported by the provider
138	*/
139	virtual QStringList supportedMACTypes() const;
140	};
141
142	/**
143	\class RandomContext qcaprovider.h QtCrypto
144
145	Random provider
146
147	\note This class is part of the provider plugin interface and should not
148	be used directly by applications. You probably want Random instead.
149
150	\ingroup ProviderAPI
151	*/
152	class QCA_EXPORT RandomContext : public BasicContext
153	{
154	Q_OBJECT
155	public:
156	/**
157	Standard constructor
158
159	\param p the provider associated with this context
160	*/
161	RandomContext(Provider *p)
162	: BasicContext(p, QStringLiteral("random"))
163	{
164	}
165
166	/**
167	Return an array of random bytes
168
169	\param size the number of random bytes to return
170	*/
171	virtual SecureArray nextBytes(int size) = 0;
172	};
173
174	/**
175	\class HashContext qcaprovider.h QtCrypto
176
177	Hash provider
178
179	\note This class is part of the provider plugin interface and should not
180	be used directly by applications. You probably want Hash instead.
181
182	\ingroup ProviderAPI
183	*/
184	class QCA_EXPORT HashContext : public BasicContext
185	{
186	Q_OBJECT
187	public:
188	/**
189	Standard constructor
190
191	\param p the provider associated with this context
192	\param type the name of the type of hash provided by this context
193	*/
194	HashContext(Provider *p, const QString &type)
195	: BasicContext(p, type)
196	{
197	}
198
199	/**
200	Reset the object to its initial state
201	*/
202	virtual void clear() = 0;
203
204	/**
205	Process a chunk of data
206
207	\param a the input data to process
208	*/
209	virtual void update(const MemoryRegion &a) = 0;
210
211	/**
212	Return the computed hash
213	*/
214	virtual MemoryRegion final() = 0;
215	};
216
217	/**
218	\class CipherContext qcaprovider.h QtCrypto
219
220	Cipher provider
221
222	\note This class is part of the provider plugin interface and should not
223	be used directly by applications. You probably want Cipher instead.
224
225	\ingroup ProviderAPI
226	*/
227	class QCA_EXPORT CipherContext : public BasicContext
228	{
229	Q_OBJECT
230	public:
231	/**
232	Standard constructor
233
234	\param p the provider associated with this context
235	\param type the name of the type of cipher provided by this context
236
237	\note type includes the name of the cipher (e.g. "aes256"), the operating
238	mode (e.g. "cbc" or "ofb") and the padding type (e.g. "pkcs7") if any.
239	*/
240	CipherContext(Provider *p, const QString &type)
241	: BasicContext(p, type)
242	{
243	}
244
245	/**
246	Set up the object for encrypt/decrypt
247
248	\param dir the direction for the cipher (encryption/decryption)
249	\param key the symmetric key to use for the cipher
250	\param iv the initialization vector to use for the cipher (not used in ECB mode)
251	\param tag the AuthTag to use (only for GCM and CCM modes)
252	*/
253	virtual void setup(Direction dir, const SymmetricKey &key, const InitializationVector &iv, const AuthTag &tag) = 0;
254
255	/**
256	Returns the KeyLength for this cipher
257	*/
258	virtual KeyLength keyLength() const = 0;
259
260	/**
261	Returns the block size for this cipher
262	*/
263	virtual int blockSize() const = 0;
264
265	/**
266	Returns the authentication tag for this cipher
267	*/
268	virtual AuthTag tag() const = 0;
269
270	/**
271	Process a chunk of data. Returns true if successful.
272
273	\param in the input data to process
274	\param out pointer to an array that should store the result
275	*/
276	virtual bool update(const SecureArray &in, SecureArray *out) = 0;
277
278	/**
279	Finish the cipher processing. Returns true if successful.
280
281	\param out pointer to an array that should store the result
282	*/
283	virtual bool final(SecureArray *out) = 0;
284	};
285
286	/**
287	\class MACContext qcaprovider.h QtCrypto
288
289	Message authentication code provider
290
291	\note This class is part of the provider plugin interface and should not
292	be used directly by applications. You probably want
293	MessageAuthenticationCode instead.
294
295	\ingroup ProviderAPI
296	*/
297	class QCA_EXPORT MACContext : public BasicContext
298	{
299	Q_OBJECT
300	public:
301	/**
302	Standard constructor
303	\param p the provider associated with this context
304	\param type the name of the type of MAC algorithm provided by this context
305	*/
306	MACContext(Provider *p, const QString &type)
307	: BasicContext(p, type)
308	{
309	}
310
311	/**
312	Set up the object for hashing
313
314	\param key the key to use with the MAC.
315	*/
316	virtual void setup(const SymmetricKey &key) = 0;
317
318	/**
319	Returns the KeyLength for this MAC algorithm
320	*/
321	virtual KeyLength keyLength() const = 0;
322
323	/**
324	Process a chunk of data
325
326	\param in the input data to process
327	*/
328	virtual void update(const MemoryRegion &in) = 0;
329
330	/**
331	Compute the result after processing all data
332
333	\param out pointer to an array that should store the result
334	*/
335	virtual void final(MemoryRegion *out) = 0;
336
337	protected:
338	/**
339	Returns a KeyLength that supports any length
340	*/
341	KeyLength anyKeyLength() const
342	{
343	// this is used instead of a default implementation to make sure that
344	// provider authors think about it, at least a bit.
345	// See Meyers, Effective C++, Effective C++ (2nd Ed), Item 36
346	return KeyLength(0, INT_MAX, 1);
347	}
348	};
349
350	/**
351	\class KDFContext qcaprovider.h QtCrypto
352
353	Key derivation function provider
354
355	\note This class is part of the provider plugin interface and should not
356	be used directly by applications. You probably want KeyDerivationFunction
357	instead.
358
359	\ingroup ProviderAPI
360	*/
361	class QCA_EXPORT KDFContext : public BasicContext
362	{
363	Q_OBJECT
364	public:
365	/**
366	Standard constructor
367
368	\param p the provider associated with this context
369	\param type the name of the KDF provided by this context (including algorithm)
370	*/
371	KDFContext(Provider *p, const QString &type)
372	: BasicContext(p, type)
373	{
374	}
375
376	/**
377	Create a key and return it
378
379	\param secret the secret part (typically password)
380	\param salt the salt / initialization vector
381	\param keyLength the length of the key to be produced
382	\param iterationCount the number of iterations of the derivation algorithm
383	*/
384	virtual SymmetricKey makeKey(const SecureArray &secret,
385	const InitializationVector &salt,
386	unsigned int keyLength,
387	unsigned int iterationCount) = 0;
388
389	/**
390	Create a key and return it
391
392	\param secret the secret part (typically password)
393	\param salt the salt / initialization vector
394	\param keyLength the length of the key to be produced
395	\param msecInterval the maximum time to compute the key, in milliseconds
396	\param iterationCount a pointer to store the number of iterations of the derivation algorithm
397	*/
398	virtual SymmetricKey makeKey(const SecureArray &secret,
399	const InitializationVector &salt,
400	unsigned int keyLength,
401	int msecInterval,
402	unsigned int *iterationCount) = 0;
403	};
404
405	/**
406	\class HKDFContext qcaprovider.h QtCrypto
407
408	HKDF provider
409
410	\note This class is part of the provider plugin interface and should not
411	be used directly by applications. You probably want HKDF instead.
412
413	\ingroup ProviderAPI
414	*/
415	class QCA_EXPORT HKDFContext : public BasicContext
416	{
417	Q_OBJECT
418	public:
419	/**
420	Standard constructor
421
422	\param p the provider associated with this context
423	\param type the name of the HKDF provided by this context (including algorithm)
424	*/
425	HKDFContext(Provider *p, const QString &type)
426	: BasicContext(p, type)
427	{
428	}
429
430	/**
431	Create a key and return it
432
433	\param secret the secret part (typically password)
434	\param salt the salt / initialization vector
435	\param info the info / initialization vector
436	\param keyLength the length of the key to be produced
437	*/
438	virtual SymmetricKey makeKey(const SecureArray &secret,
439	const InitializationVector &salt,
440	const InitializationVector &info,
441	unsigned int keyLength) = 0;
442	};
443
444	/**
445	\class DLGroupContext qcaprovider.h QtCrypto
446
447	Discrete logarithm provider
448
449	\note This class is part of the provider plugin interface and should not
450	be used directly by applications. You probably want DLGroup instead.
451
452	\ingroup ProviderAPI
453	*/
454	class QCA_EXPORT DLGroupContext : public Provider::Context
455	{
456	Q_OBJECT
457	public:
458	/**
459	Standard constructor
460
461	\param p the provider associated with this context
462	*/
463	DLGroupContext(Provider *p)
464	: Provider::Context(p, QStringLiteral("dlgroup"))
465	{
466	}
467
468	/**
469	The DLGroupSets supported by this object
470	*/
471	virtual QList<DLGroupSet> supportedGroupSets() const = 0;
472
473	/**
474	Returns true if there is a result to obtain
475	*/
476	virtual bool isNull() const = 0;
477
478	/**
479	Attempt to create P, Q, and G values from the specified group set
480
481	If \a block is true, then this function blocks until completion.
482	Otherwise, this function returns immediately and finished() is
483	emitted when the operation completes.
484
485	If an error occurs during generation, then the operation will
486	complete and isNull() will return true.
487
488	\param set the group set to generate the key from
489	\param block whether to block (true) or not (false)
490	*/
491	virtual void fetchGroup(DLGroupSet set, bool block) = 0;
492
493	/**
494	Obtain the result of the operation. Ensure isNull() returns false
495	before calling this function.
496
497	\param p the P value
498	\param q the Q value
499	\param g the G value
500	*/
501	virtual void getResult(BigInteger *p, BigInteger *q, BigInteger *g) const = 0;
502
503	Q_SIGNALS:
504	/**
505	Emitted when the fetchGroup() operation completes in non-blocking
506	mode.
507	*/
508	void finished();
509	};
510
511	/**
512	\class PKeyBase qcaprovider.h QtCrypto
513
514	Public key implementation provider base
515
516	\note This class is part of the provider plugin interface and should not
517	be used directly by applications. You probably want PKey, PublicKey, or
518	PrivateKey instead.
519
520	\ingroup ProviderAPI
521	*/
522	class QCA_EXPORT PKeyBase : public BasicContext
523	{
524	Q_OBJECT
525	public:
526	/**
527	Standard constructor
528
529	\param p the Provider associated with this context
530	\param type type of key provided by this context
531	*/
532	PKeyBase(Provider *p, const QString &type);
533
534	/**
535	Returns true if this object is not valid. This is the default
536	state, and the object may also become this state if a conversion
537	or generation function fails.
538	*/
539	virtual bool isNull() const = 0;
540
541	/**
542	Returns the type of public key
543	*/
544	virtual PKey::Type type() const = 0;
545
546	/**
547	Returns true if this is a private key, otherwise false
548	*/
549	virtual bool isPrivate() const = 0;
550
551	/**
552	Returns true if the components of this key are accessible and
553	whether it can be serialized into an output format. Private keys
554	from a smart card device will often not be exportable.
555	*/
556	virtual bool canExport() const = 0;
557
558	/**
559	If the key is a private key, this function will convert it into a
560	public key (all private key data includes the public data as well,
561	which is why this is possible). If the key is already a public
562	key, then this function has no effect.
563	*/
564	virtual void convertToPublic() = 0;
565
566	/**
567	Returns the number of bits in the key
568	*/
569	virtual int bits() const = 0;
570
571	/**
572	Returns the maximum number of bytes that can be encrypted by this
573	key
574
575	\param alg the algorithm to be used for encryption
576	*/
577	virtual int maximumEncryptSize(EncryptionAlgorithm alg) const;
578
579	/**
580	Encrypt data
581
582	\param in the input data to encrypt
583	\param alg the encryption algorithm to use
584	*/
585	virtual SecureArray encrypt(const SecureArray &in, EncryptionAlgorithm alg);
586
587	/**
588	Decrypt data
589
590	\param in the input data to decrypt
591	\param out pointer to an array to store the plaintext result
592	\param alg the encryption algorithm used to generate the input
593	data
594	*/
595	virtual bool decrypt(const SecureArray &in, SecureArray *out, EncryptionAlgorithm alg);
596
597	/**
598	Begin a signing operation
599
600	\param alg the signature algorithm to use
601	\param format the signature format to use
602	*/
603	virtual void startSign(SignatureAlgorithm alg, SignatureFormat format);
604
605	/**
606	Begin a verify operation
607
608	\param alg the signature algorithm used by the input signature
609	\param format the signature format used by the input signature
610	*/
611	virtual void startVerify(SignatureAlgorithm alg, SignatureFormat format);
612
613	/**
614	Process the plaintext input data for either signing or verifying,
615	whichever operation is active.
616
617	\param in the input data to process
618	*/
619	virtual void update(const MemoryRegion &in);
620
621	/**
622	Complete a signing operation, and return the signature value
623
624	If there is an error signing, an empty array is returned.
625	*/
626	virtual QByteArray endSign();
627
628	/**
629	Complete a verify operation, and return true if successful
630
631	If there is an error verifying, this function returns false.
632
633	\param sig the signature to verify with the input data
634	*/
635	virtual bool endVerify(const QByteArray &sig);
636
637	/**
638	Compute a symmetric key based on this private key and some other
639	public key
640
641	Essentially for Diffie-Hellman only.
642
643	\param theirs the other side (public key) to be used for key generation.
644	*/
645	virtual SymmetricKey deriveKey(const PKeyBase &theirs);
646
647	Q_SIGNALS:
648	/**
649	Emitted when an asynchronous operation completes on this key.
650	Such operations will be documented that they emit this signal.
651	*/
652	void finished();
653	};
654
655	/**
656	\class RSAContext qcaprovider.h QtCrypto
657
658	RSA provider
659
660	\note This class is part of the provider plugin interface and should not
661	be used directly by applications. You probably want RSAPublicKey or
662	RSAPrivateKey instead.
663
664	\ingroup ProviderAPI
665	*/
666	class QCA_EXPORT RSAContext : public PKeyBase
667	{
668	Q_OBJECT
669	public:
670	/**
671	Standard constructor
672
673	\param p the provider associated with this context
674	*/
675	RSAContext(Provider *p)
676	: PKeyBase(p, QStringLiteral("rsa"))
677	{
678	}
679
680	/**
681	Generate an RSA private key
682
683	If \a block is true, then this function blocks until completion.
684	Otherwise, this function returns immediately and finished() is
685	emitted when the operation completes.
686
687	If an error occurs during generation, then the operation will
688	complete and isNull() will return true.
689
690	\param bits the length of the key to generate, in bits
691	\param exp the exponent to use for generation
692	\param block whether to use blocking mode
693	*/
694	virtual void createPrivate(int bits, int exp, bool block) = 0;
695
696	/**
697	Create an RSA private key based on the five components
698
699	\param n the N parameter
700	\param e the public exponent
701	\param p the P parameter
702	\param q the Q parameter
703	\param d the D parameter
704	*/
705	virtual void createPrivate(const BigInteger &n,
706	const BigInteger &e,
707	const BigInteger &p,
708	const BigInteger &q,
709	const BigInteger &d) = 0;
710
711	/**
712	Create an RSA public key based on the two public components
713
714	\param n the N parameter
715	\param e the public exponent
716	*/
717	virtual void createPublic(const BigInteger &n, const BigInteger &e) = 0;
718
719	/**
720	Returns the public N component of this RSA key
721	*/
722	virtual BigInteger n() const = 0;
723
724	/**
725	Returns the public E component of this RSA key
726	*/
727	virtual BigInteger e() const = 0;
728
729	/**
730	Returns the private P component of this RSA key
731	*/
732	virtual BigInteger p() const = 0;
733
734	/**
735	Returns the private Q component of this RSA key
736	*/
737	virtual BigInteger q() const = 0;
738
739	/**
740	Returns the private D component of this RSA key
741	*/
742	virtual BigInteger d() const = 0;
743	};
744
745	/**
746	\class DSAContext qcaprovider.h QtCrypto
747
748	DSA provider
749
750	\note This class is part of the provider plugin interface and should not
751	be used directly by applications. You probably want DSAPublicKey or
752	DSAPrivateKey instead.
753
754	\ingroup ProviderAPI
755	*/
756	class QCA_EXPORT DSAContext : public PKeyBase
757	{
758	Q_OBJECT
759	public:
760	/**
761	Standard constructor
762
763	\param p the provider associated with this context
764	*/
765	DSAContext(Provider *p)
766	: PKeyBase(p, QStringLiteral("dsa"))
767	{
768	}
769
770	/**
771	Generate a DSA private key
772
773	If \a block is true, then this function blocks until completion.
774	Otherwise, this function returns immediately and finished() is
775	emitted when the operation completes.
776
777	If an error occurs during generation, then the operation will
778	complete and isNull() will return true.
779
780	\param domain the domain values to use for generation
781	\param block whether to use blocking mode
782	*/
783	virtual void createPrivate(const DLGroup &domain, bool block) = 0;
784
785	/**
786	Create a DSA private key based on its numeric components
787
788	\param domain the domain values to use for generation
789	\param y the public Y component
790	\param x the private X component
791	*/
792	virtual void createPrivate(const DLGroup &domain, const BigInteger &y, const BigInteger &x) = 0;
793
794	/**
795	Create a DSA public key based on its numeric components
796
797	\param domain the domain values to use for generation
798	\param y the public Y component
799	*/
800	virtual void createPublic(const DLGroup &domain, const BigInteger &y) = 0;
801
802	/**
803	Returns the public domain component of this DSA key
804	*/
805	virtual DLGroup domain() const = 0;
806
807	/**
808	Returns the public Y component of this DSA key
809	*/
810	virtual BigInteger y() const = 0;
811
812	/**
813	Returns the private X component of this DSA key
814	*/
815	virtual BigInteger x() const = 0;
816	};
817
818	/**
819	\class DHContext qcaprovider.h QtCrypto
820
821	Diffie-Hellman provider
822
823	\note This class is part of the provider plugin interface and should not
824	be used directly by applications. You probably want DHPublicKey or
825	DHPrivateKey instead.
826
827	\ingroup ProviderAPI
828	*/
829	class QCA_EXPORT DHContext : public PKeyBase
830	{
831	Q_OBJECT
832	public:
833	/**
834	Standard constructor
835
836	\param p the provider associated with this context
837	*/
838	DHContext(Provider *p)
839	: PKeyBase(p, QStringLiteral("dh"))
840	{
841	}
842
843	/**
844	Generate a Diffie-Hellman private key
845
846	If \a block is true, then this function blocks until completion.
847	Otherwise, this function returns immediately and finished() is
848	emitted when the operation completes.
849
850	If an error occurs during generation, then the operation will
851	complete and isNull() will return true.
852
853	\param domain the domain values to use for generation
854	\param block whether to use blocking mode
855	*/
856	virtual void createPrivate(const DLGroup &domain, bool block) = 0;
857
858	/**
859	Create a Diffie-Hellman private key based on its numeric
860	components
861
862	\param domain the domain values to use for generation
863	\param y the public Y component
864	\param x the private X component
865	*/
866	virtual void createPrivate(const DLGroup &domain, const BigInteger &y, const BigInteger &x) = 0;
867
868	/**
869	Create a Diffie-Hellman public key based on its numeric
870	components
871
872	\param domain the domain values to use for generation
873	\param y the public Y component
874	*/
875	virtual void createPublic(const DLGroup &domain, const BigInteger &y) = 0;
876
877	/**
878	Returns the public domain component of this Diffie-Hellman key
879	*/
880	virtual DLGroup domain() const = 0;
881
882	/**
883	Returns the public Y component of this Diffie-Hellman key
884	*/
885	virtual BigInteger y() const = 0;
886
887	/**
888	Returns the private X component of this Diffie-Hellman key
889	*/
890	virtual BigInteger x() const = 0;
891	};
892
893	/**
894	\class PKeyContext qcaprovider.h QtCrypto
895
896	Public key container provider
897
898	\note This class is part of the provider plugin interface and should not
899	be used directly by applications. You probably want PKey, PublicKey, or
900	PrivateKey instead.
901
902	This object "holds" a public key object. By default it contains no key
903	(key() returns 0), but you can put a key into it with setKey(), or you
904	can call an import function such as publicFromDER().
905
906	\ingroup ProviderAPI
907	*/
908	class QCA_EXPORT PKeyContext : public BasicContext
909	{
910	Q_OBJECT
911	public:
912	/**
913	Standard constructor
914
915	\param p the provider associated with this context
916	*/
917	PKeyContext(Provider *p)
918	: BasicContext(p, QStringLiteral("pkey"))
919	{
920	}
921
922	/**
923	Returns a list of supported public key types
924	*/
925	virtual QList<PKey::Type> supportedTypes() const = 0;
926
927	/**
928	Returns a list of public key types that can be serialized and
929	deserialized into DER and PEM format
930	*/
931	virtual QList<PKey::Type> supportedIOTypes() const = 0;
932
933	/**
934	Returns a list of password-based encryption algorithms that are
935	supported for private key serialization and deserialization
936	*/
937	virtual QList<PBEAlgorithm> supportedPBEAlgorithms() const = 0;
938
939	/**
940	Returns the key held by this object, or 0 if there is no key
941	*/
942	virtual PKeyBase *key() = 0;
943
944	/**
945	Returns the key held by this object, or 0 if there is no key
946	*/
947	virtual const PKeyBase *key() const = 0;
948
949	/**
950	Sets the key for this object. If this object already had a key,
951	then the old one is destructed. This object takes ownership of
952	the key.
953
954	\param key the key to be set for this object
955	*/
956	virtual void setKey(PKeyBase *key) = 0;
957
958	/**
959	Attempt to import a key from another provider. Returns true if
960	successful, otherwise false.
961
962	Generally this function is used if the specified key's provider
963	does not support serialization, but your provider does. The call
964	to this function would then be followed by an export function,
965	such as publicToDER().
966
967	\param key the key to be imported
968	*/
969	virtual bool importKey(const PKeyBase *key) = 0;
970
971	/**
972	Convert a public key to DER format, and return the value
973
974	Returns an empty array on error.
975	*/
976	virtual QByteArray publicToDER() const;
977
978	/**
979	Convert a public key to PEM format, and return the value
980
981	Returns an empty string on error.
982	*/
983	virtual QString publicToPEM() const;
984
985	/**
986	Read DER-formatted input and convert it into a public key
987
988	Returns QCA::ConvertGood if successful, otherwise some error
989	value.
990
991	\param a the input data
992	*/
993	virtual ConvertResult publicFromDER(const QByteArray &a);
994
995	/**
996	Read PEM-formatted input and convert it into a public key
997
998	Returns QCA::ConvertGood if successful, otherwise some error
999	value.
1000
1001	\param s the input data
1002	*/
1003	virtual ConvertResult publicFromPEM(const QString &s);
1004
1005	/**
1006	Convert a private key to DER format, and return the value
1007
1008	Returns an empty array on error.
1009
1010	\param passphrase the passphrase to encode the result with, or an
1011	empty array if no encryption is desired
1012	\param pbe the encryption algorithm to use, if applicable
1013	*/
1014	virtual SecureArray privateToDER(const SecureArray &passphrase, PBEAlgorithm pbe) const;
1015
1016	/**
1017	Convert a private key to PEM format, and return the value
1018
1019	Returns an empty string on error.
1020
1021	\param passphrase the passphrase to encode the result with, or an
1022	empty array if no encryption is desired
1023	\param pbe the encryption algorithm to use, if applicable
1024	*/
1025	virtual QString privateToPEM(const SecureArray &passphrase, PBEAlgorithm pbe) const;
1026
1027	/**
1028	Read DER-formatted input and convert it into a private key
1029
1030	Returns QCA::ConvertGood if successful, otherwise some error
1031	value.
1032
1033	\param a the input data
1034	\param passphrase the passphrase needed to decrypt, if applicable
1035	*/
1036	virtual ConvertResult privateFromDER(const SecureArray &a, const SecureArray &passphrase);
1037
1038	/**
1039	Read PEM-formatted input and convert it into a private key
1040
1041	Returns QCA::ConvertGood if successful, otherwise some error
1042	value.
1043
1044	\param s the input data
1045	\param passphrase the passphrase needed to decrypt, if applicable
1046	*/
1047	virtual ConvertResult privateFromPEM(const QString &s, const SecureArray &passphrase);
1048	};
1049
1050	/**
1051	\class CertBase qcaprovider.h QtCrypto
1052
1053	X.509 certificate and certificate request provider base
1054
1055	\note This class is part of the provider plugin interface and should not
1056	be used directly by applications. You probably want Certificate,
1057	CertificateRequest, or CRL instead.
1058
1059	\ingroup ProviderAPI
1060	*/
1061	class QCA_EXPORT CertBase : public BasicContext
1062	{
1063	Q_OBJECT
1064	public:
1065	/**
1066	Standard constructor
1067
1068	\param p the provider associated with this context
1069	\param type the type of certificate-like object provided by this context
1070	*/
1071	CertBase(Provider *p, const QString &type)
1072	: BasicContext(p, type)
1073	{
1074	}
1075
1076	/**
1077	Convert this object to DER format, and return the value
1078
1079	Returns an empty array on error.
1080	*/
1081	virtual QByteArray toDER() const = 0;
1082
1083	/**
1084	Convert this object to PEM format, and return the value
1085
1086	Returns an empty string on error.
1087	*/
1088	virtual QString toPEM() const = 0;
1089
1090	/**
1091	Read DER-formatted input and convert it into this object
1092
1093	Returns QCA::ConvertGood if successful, otherwise some error
1094	value.
1095
1096	\param a the input data
1097	*/
1098	virtual ConvertResult fromDER(const QByteArray &a) = 0;
1099
1100	/**
1101	Read PEM-formatted input and convert it into this object
1102
1103	Returns QCA::ConvertGood if successful, otherwise some error
1104	value.
1105
1106	\param s the input data
1107	*/
1108	virtual ConvertResult fromPEM(const QString &s) = 0;
1109	};
1110
1111	/**
1112	\class CertContextProps qcaprovider.h QtCrypto
1113
1114	X.509 certificate or certificate request properties
1115
1116	\note This class is part of the provider plugin interface and should not
1117	be used directly by applications. You probably want Certificate or
1118	CertificateRequest instead.
1119
1120	Some fields are only for certificates or only for certificate requests,
1121	and these fields are noted.
1122
1123	\ingroup ProviderAPI
1124	*/
1125	class QCA_EXPORT CertContextProps
1126	{
1127	public:
1128	/**
1129	The X.509 certificate version, usually 3
1130
1131	This field is for certificates only.
1132	*/
1133	int version;
1134
1135	/**
1136	The time the certificate becomes valid (often the time of create)
1137
1138	This field is for certificates only.
1139	*/
1140	QDateTime start;
1141
1142	/**
1143	The time the certificate expires
1144
1145	This field is for certificates only.
1146	*/
1147	QDateTime end;
1148
1149	/**
1150	The subject information
1151	*/
1152	CertificateInfoOrdered subject;
1153
1154	/**
1155	The issuer information
1156
1157	This field is for certificates only.
1158	*/
1159	CertificateInfoOrdered issuer;
1160
1161	/**
1162	The constraints
1163	*/
1164	Constraints constraints;
1165
1166	/**
1167	The policies
1168	*/
1169	QStringList policies;
1170
1171	/**
1172	A list of URIs for CRLs
1173
1174	This field is for certificates only.
1175	*/
1176	QStringList crlLocations;
1177
1178	/**
1179	A list of URIs for issuer certificates
1180
1181	This field is for certificates only.
1182	*/
1183	QStringList issuerLocations;
1184
1185	/**
1186	A list of URIs for OCSP services
1187
1188	This field is for certificates only.
1189	*/
1190	QStringList ocspLocations;
1191
1192	/**
1193	The certificate serial number
1194
1195	This field is for certificates only.
1196	*/
1197	BigInteger serial;
1198
1199	/**
1200	True if the certificate is a CA or the certificate request is
1201	requesting to be a CA, otherwise false
1202	*/
1203	bool isCA;
1204
1205	/**
1206	True if the certificate is self-signed
1207
1208	This field is for certificates only.
1209	*/
1210	bool isSelfSigned;
1211
1212	/**
1213	The path limit
1214	*/
1215	int pathLimit;
1216
1217	/**
1218	The signature data
1219	*/
1220	QByteArray sig;
1221
1222	/**
1223	The signature algorithm used to create the signature
1224	*/
1225	SignatureAlgorithm sigalgo;
1226
1227	/**
1228	The subject id
1229
1230	This field is for certificates only.
1231	*/
1232	QByteArray subjectId;
1233
1234	/**
1235	The issuer id
1236
1237	This field is for certificates only.
1238	*/
1239	QByteArray issuerId;
1240
1241	/**
1242	The SPKAC challenge value
1243
1244	This field is for certificate requests only.
1245	*/
1246	QString challenge;
1247
1248	/**
1249	The format used for the certificate request
1250
1251	This field is for certificate requests only.
1252	*/
1253	CertificateRequestFormat format;
1254	};
1255
1256	/**
1257	\class CRLContextProps qcaprovider.h QtCrypto
1258
1259	X.509 certificate revocation list properties
1260
1261	\note This class is part of the provider plugin interface and should not
1262	be used directly by applications. You probably want CRL instead.
1263
1264	For efficiency and simplicity, the members are directly accessed.
1265
1266	\ingroup ProviderAPI
1267	*/
1268	class QCA_EXPORT CRLContextProps
1269	{
1270	public:
1271	/**
1272	The issuer information of the CRL
1273	*/
1274	CertificateInfoOrdered issuer;
1275
1276	/**
1277	The CRL number, which increases at each update
1278	*/
1279	int number;
1280
1281	/**
1282	The time this CRL was created
1283	*/
1284	QDateTime thisUpdate;
1285
1286	/**
1287	The time this CRL expires, and the next CRL should be fetched
1288	*/
1289	QDateTime nextUpdate;
1290
1291	/**
1292	The revoked entries
1293	*/
1294	QList<CRLEntry> revoked;
1295
1296	/**
1297	The signature data of the CRL
1298	*/
1299	QByteArray sig;
1300
1301	/**
1302	The signature algorithm used by the issuer to sign the CRL
1303	*/
1304	SignatureAlgorithm sigalgo;
1305
1306	/**
1307	The issuer id
1308	*/
1309	QByteArray issuerId;
1310	};
1311
1312	class CRLContext;
1313
1314	/**
1315	\class CertContext qcaprovider.h QtCrypto
1316
1317	X.509 certificate provider
1318
1319	\note This class is part of the provider plugin interface and should not
1320	be used directly by applications. You probably want Certificate instead.
1321
1322	\ingroup ProviderAPI
1323	*/
1324	class QCA_EXPORT CertContext : public CertBase
1325	{
1326	Q_OBJECT
1327	public:
1328	/**
1329	Standard constructor
1330
1331	\param p the provider associated with this context
1332	*/
1333	CertContext(Provider *p)
1334	: CertBase(p, QStringLiteral("cert"))
1335	{
1336	}
1337
1338	/**
1339	Create a self-signed certificate based on the given options and
1340	private key. Returns true if successful, otherwise false.
1341
1342	If successful, this object becomes the self-signed certificate.
1343	If unsuccessful, this object is considered to be in an
1344	uninitialized state.
1345
1346	\param opts the options to set on the certificate
1347	\param priv the key to be used to sign the certificate
1348	*/
1349	virtual bool createSelfSigned(const CertificateOptions &opts, const PKeyContext &priv) = 0;
1350
1351	/**
1352	Returns a pointer to the properties of this certificate
1353	*/
1354	virtual const CertContextProps *props() const = 0;
1355
1356	/**
1357	Returns true if this certificate is equal to another certificate,
1358	otherwise false
1359
1360	\param other the certificate to compare with
1361	*/
1362	virtual bool compare(const CertContext *other) const = 0;
1363
1364	/**
1365	Returns a copy of this certificate's public key. The caller is
1366	responsible for deleting it.
1367	*/
1368	virtual PKeyContext *subjectPublicKey() const = 0;
1369
1370	/**
1371	Returns true if this certificate is an issuer of another
1372	certificate, otherwise false
1373
1374	\param other the issued certificate to check
1375	*/
1376	virtual bool isIssuerOf(const CertContext *other) const = 0;
1377
1378	/**
1379	Validate this certificate
1380
1381	This function is blocking.
1382
1383	\param trusted list of trusted certificates
1384	\param untrusted list of untrusted certificates (can be empty)
1385	\param crls list of CRLs (can be empty)
1386	\param u the desired usage for this certificate
1387	\param vf validation options
1388	*/
1389	virtual Validity validate(const QList<CertContext *> &trusted,
1390	const QList<CertContext *> &untrusted,
1391	const QList<CRLContext *> &crls,
1392	UsageMode u,
1393	ValidateFlags vf) const = 0;
1394
1395	/**
1396	Validate a certificate chain. This function makes no use of the
1397	certificate represented by this object, and it can be used even
1398	if this object is in an uninitialized state.
1399
1400	This function is blocking.
1401
1402	\param chain list of certificates in the chain, starting with the
1403	user certificate. It is not necessary for the chain to contain
1404	the final root certificate.
1405	\param trusted list of trusted certificates
1406	\param crls list of CRLs (can be empty)
1407	\param u the desired usage for the user certificate in the chain
1408	\param vf validation options
1409	*/
1410	virtual Validity validate_chain(const QList<CertContext *> &chain,
1411	const QList<CertContext *> &trusted,
1412	const QList<CRLContext *> &crls,
1413	UsageMode u,
1414	ValidateFlags vf) const = 0;
1415	};
1416
1417	/**
1418	\class CSRContext qcaprovider.h QtCrypto
1419
1420	X.509 certificate request provider
1421
1422	\note This class is part of the provider plugin interface and should not
1423	be used directly by applications. You probably want CertificateRequest
1424	instead.
1425
1426	\ingroup ProviderAPI
1427	*/
1428	class QCA_EXPORT CSRContext : public CertBase
1429	{
1430	Q_OBJECT
1431	public:
1432	/**
1433	Standard constructor
1434
1435	\param p the provider associated with this context
1436	*/
1437	CSRContext(Provider *p)
1438	: CertBase(p, QStringLiteral("csr"))
1439	{
1440	}
1441
1442	/**
1443	Returns true if the provider of this object supports the specified
1444	format, otherwise false
1445
1446	\param f the format to test for support for.
1447	*/
1448	virtual bool canUseFormat(CertificateRequestFormat f) const = 0;
1449
1450	/**
1451	Create a certificate request based on the given options and
1452	private key. Returns true if successful, otherwise false.
1453
1454	If successful, this object becomes the certificate request.
1455	If unsuccessful, this object is considered to be in an
1456	uninitialized state.
1457
1458	\param opts the options to set on the certificate
1459	\param priv the key to be used to sign the certificate
1460	*/
1461	virtual bool createRequest(const CertificateOptions &opts, const PKeyContext &priv) = 0;
1462
1463	/**
1464	Returns a pointer to the properties of this certificate request
1465	*/
1466	virtual const CertContextProps *props() const = 0;
1467
1468	/**
1469	Returns true if this certificate request is equal to another
1470	certificate request, otherwise false
1471
1472	\param other the certificate request to compare with
1473	*/
1474	virtual bool compare(const CSRContext *other) const = 0;
1475
1476	/**
1477	Returns a copy of this certificate request's public key. The
1478	caller is responsible for deleting it.
1479	*/
1480	virtual PKeyContext *subjectPublicKey() const = 0;
1481
1482	/**
1483	Convert this certificate request to Netscape SPKAC format, and
1484	return the value
1485
1486	Returns an empty string on error.
1487	*/
1488	virtual QString toSPKAC() const = 0;
1489
1490	/**
1491	Read Netscape SPKAC input and convert it into a certificate
1492	request
1493
1494	Returns QCA::ConvertGood if successful, otherwise some error
1495	value.
1496
1497	\param s the input data
1498	*/
1499	virtual ConvertResult fromSPKAC(const QString &s) = 0;
1500	};
1501
1502	/**
1503	\class CRLContext qcaprovider.h QtCrypto
1504
1505	X.509 certificate revocation list provider
1506
1507	\note This class is part of the provider plugin interface and should not
1508	be used directly by applications. You probably want CRL instead.
1509
1510	\ingroup ProviderAPI
1511	*/
1512	class QCA_EXPORT CRLContext : public CertBase
1513	{
1514	Q_OBJECT
1515	public:
1516	/**
1517	Standard constructor
1518
1519	\param p the provider associated with this context
1520	*/
1521	CRLContext(Provider *p)
1522	: CertBase(p, QStringLiteral("crl"))
1523	{
1524	}
1525
1526	/**
1527	Returns a pointer to the properties of this CRL
1528	*/
1529	virtual const CRLContextProps *props() const = 0;
1530
1531	/**
1532	Returns true if this CRL is equal to another CRL, otherwise false
1533
1534	\param other the CRL to compare with
1535	*/
1536	virtual bool compare(const CRLContext *other) const = 0;
1537	};
1538
1539	/**
1540	\class CertCollectionContext qcaprovider.h QtCrypto
1541
1542	X.509 certificate collection provider
1543
1544	\note This class is part of the provider plugin interface and should not
1545	be used directly by applications. You probably want CertificateCollection
1546	instead.
1547
1548	\ingroup ProviderAPI
1549	*/
1550	class QCA_EXPORT CertCollectionContext : public BasicContext
1551	{
1552	Q_OBJECT
1553	public:
1554	/**
1555	Standard constructor
1556
1557	\param p the provider associated with this context
1558	*/
1559	CertCollectionContext(Provider *p)
1560	: BasicContext(p, QStringLiteral("certcollection"))
1561	{
1562	}
1563
1564	/**
1565	Create PKCS#7 DER output based on the input certificates and CRLs
1566
1567	Returns an empty array on error.
1568
1569	\param certs list of certificates to store in the output
1570	\param crls list of CRLs to store in the output
1571	*/
1572	virtual QByteArray toPKCS7(const QList<CertContext *> &certs, const QList<CRLContext *> &crls) const = 0;
1573
1574	/**
1575	Read PKCS#7 DER input and convert it into a list of certificates
1576	and CRLs
1577
1578	The caller is responsible for deleting the returned items.
1579
1580	Returns QCA::ConvertGood if successful, otherwise some error
1581	value.
1582
1583	\param a the input data
1584	\param certs the destination list for the certificates
1585	\param crls the destination list for the CRLs
1586	*/
1587	virtual ConvertResult
1588	fromPKCS7(const QByteArray &a, QList<CertContext *> *certs, QList<CRLContext *> *crls) const = 0;
1589	};
1590
1591	/**
1592	\class CAContext qcaprovider.h QtCrypto
1593
1594	X.509 certificate authority provider
1595
1596	\note This class is part of the provider plugin interface and should not
1597	be used directly by applications. You probably want CertificateAuthority
1598	instead.
1599
1600	\ingroup ProviderAPI
1601	*/
1602	class QCA_EXPORT CAContext : public BasicContext
1603	{
1604	Q_OBJECT
1605	public:
1606	/**
1607	Standard constructor
1608
1609	\param p the Provider associated with this context
1610	*/
1611	CAContext(Provider *p)
1612	: BasicContext(p, QStringLiteral("ca"))
1613	{
1614	}
1615
1616	/**
1617	Prepare the object for usage
1618
1619	This must be called before any CA operations are performed.
1620
1621	\param cert the certificate of the CA
1622	\param priv the private key of the CA
1623	*/
1624	virtual void setup(const CertContext &cert, const PKeyContext &priv) = 0;
1625
1626	/**
1627	Returns a copy of the CA's certificate. The caller is responsible
1628	for deleting it.
1629	*/
1630	virtual CertContext *certificate() const = 0;
1631
1632	/**
1633	Issue a certificate based on a certificate request, and return
1634	the certificate. The caller is responsible for deleting it.
1635
1636	\param req the certificate request
1637	\param notValidAfter the expiration date
1638	*/
1639	virtual CertContext *signRequest(const CSRContext &req, const QDateTime &notValidAfter) const = 0;
1640
1641	/**
1642	Issue a certificate based on a public key and options, and return
1643	the certificate. The caller is responsible for deleting it.
1644
1645	\param pub the public key of the certificate
1646	\param opts the options to use for generation
1647	*/
1648	virtual CertContext *createCertificate(const PKeyContext &pub, const CertificateOptions &opts) const = 0;
1649
1650	/**
1651	Create a new CRL and return it. The caller is responsible for
1652	deleting it.
1653
1654	The CRL has no entries in it.
1655
1656	\param nextUpdate the expiration date of the CRL
1657	*/
1658	virtual CRLContext *createCRL(const QDateTime &nextUpdate) const = 0;
1659
1660	/**
1661	Update an existing CRL, by examining an old one and creating a new
1662	one based on it. The new CRL is returned, and the caller is
1663	responsible for deleting it.
1664
1665	\param crl an existing CRL issued by this CA
1666	\param entries the list of revoked entries
1667	\param nextUpdate the expiration date of the new CRL
1668	*/
1669	virtual CRLContext *
1670	updateCRL(const CRLContext &crl, const QList<CRLEntry> &entries, const QDateTime &nextUpdate) const = 0;
1671	};
1672
1673	/**
1674	\class PKCS12Context qcaprovider.h QtCrypto
1675
1676	PKCS#12 provider
1677
1678	\note This class is part of the provider plugin interface and should not
1679	be used directly by applications. You probably want KeyBundle instead.
1680
1681	\ingroup ProviderAPI
1682	*/
1683	class QCA_EXPORT PKCS12Context : public BasicContext
1684	{
1685	Q_OBJECT
1686	public:
1687	/**
1688	Standard constructor
1689
1690	\param p the Provider associated with this context
1691	*/
1692	PKCS12Context(Provider *p)
1693	: BasicContext(p, QStringLiteral("pkcs12"))
1694	{
1695	}
1696
1697	/**
1698	Create PKCS#12 DER output based on a set of input items
1699
1700	Returns an empty array on error.
1701
1702	\param name the friendly name of the data
1703	\param chain the certificate chain to store
1704	\param priv the private key to store
1705	\param passphrase the passphrase to encrypt the PKCS#12 data with
1706	*/
1707	virtual QByteArray toPKCS12(const QString &name,
1708	const QList<const CertContext *> &chain,
1709	const PKeyContext &priv,
1710	const SecureArray &passphrase) const = 0;
1711
1712	/**
1713	Read PKCS#12 DER input and convert it into a set of output items
1714
1715	The caller is responsible for deleting the returned items.
1716
1717	Returns QCA::ConvertGood if successful, otherwise some error
1718	value.
1719
1720	\param in the input data
1721	\param passphrase the passphrase needed to decrypt the input data
1722	\param name the destination string for the friendly name
1723	\param chain the destination list for the certificate chain
1724	\param priv address of a pointer to accept the private key
1725	*/
1726	virtual ConvertResult fromPKCS12(const QByteArray &in,
1727	const SecureArray &passphrase,
1728	QString *name,
1729	QList<CertContext *> *chain,
1730	PKeyContext **priv) const = 0;
1731	};
1732
1733	/**
1734	\class PGPKeyContextProps qcaprovider.h QtCrypto
1735
1736	OpenPGP key properties
1737
1738	\note This class is part of the provider plugin interface and should not
1739	be used directly by applications. You probably want PGPKey instead.
1740
1741	For efficiency and simplicity, the members are directly accessed.
1742
1743	\ingroup ProviderAPI
1744	*/
1745	class QCA_EXPORT PGPKeyContextProps
1746	{
1747	public:
1748	/**
1749	The key id
1750	*/
1751	QString keyId;
1752
1753	/**
1754	List of user id strings for the key, the first one being the
1755	primary user id
1756	*/
1757	QStringList userIds;
1758
1759	/**
1760	True if this key is a secret key, otherwise false
1761	*/
1762	bool isSecret;
1763
1764	/**
1765	The time the key was created
1766	*/
1767	QDateTime creationDate;
1768
1769	/**
1770	The time the key expires
1771	*/
1772	QDateTime expirationDate;
1773
1774	/**
1775	The hex fingerprint of the key
1776
1777	The format is all lowercase with no spaces.
1778	*/
1779	QString fingerprint;
1780
1781	/**
1782	True if this key is in a keyring (and thus usable), otherwise
1783	false
1784	*/
1785	bool inKeyring;
1786
1787	/**
1788	True if this key is trusted (e.g. signed by the keyring owner or
1789	via some web-of-trust), otherwise false
1790	*/
1791	bool isTrusted;
1792	};
1793
1794	/**
1795	\class PGPKeyContext qcaprovider.h QtCrypto
1796
1797	OpenPGP key provider
1798
1799	\note This class is part of the provider plugin interface and should not
1800	be used directly by applications. You probably want PGPKey instead.
1801
1802	\ingroup ProviderAPI
1803	*/
1804	class QCA_EXPORT PGPKeyContext : public BasicContext
1805	{
1806	Q_OBJECT
1807	public:
1808	/**
1809	Standard constructor
1810
1811	\param p the Provider associated with this context
1812	*/
1813	PGPKeyContext(Provider *p)
1814	: BasicContext(p, QStringLiteral("pgpkey"))
1815	{
1816	}
1817
1818	/**
1819	Returns a pointer to the properties of this key
1820	*/
1821	virtual const PGPKeyContextProps *props() const = 0;
1822
1823	/**
1824	Convert the key to binary format, and return the value
1825	*/
1826	virtual QByteArray toBinary() const = 0;
1827
1828	/**
1829	Convert the key to ascii-armored format, and return the value
1830	*/
1831	virtual QString toAscii() const = 0;
1832
1833	/**
1834	Read binary input and convert it into a key
1835
1836	Returns QCA::ConvertGood if successful, otherwise some error
1837	value.
1838
1839	\param a the input data
1840	*/
1841	virtual ConvertResult fromBinary(const QByteArray &a) = 0;
1842
1843	/**
1844	Read ascii-armored input and convert it into a key
1845
1846	Returns QCA::ConvertGood if successful, otherwise some error
1847	value.
1848
1849	\param s the input data
1850	*/
1851	virtual ConvertResult fromAscii(const QString &s) = 0;
1852	};
1853
1854	/**
1855	\class KeyStoreEntryContext qcaprovider.h QtCrypto
1856
1857	KeyStoreEntry provider
1858
1859	\note This class is part of the provider plugin interface and should not
1860	be used directly by applications. You probably want KeyStoreEntry
1861	instead.
1862
1863	\ingroup ProviderAPI
1864	*/
1865	class QCA_EXPORT KeyStoreEntryContext : public BasicContext
1866	{
1867	Q_OBJECT
1868	public:
1869	/**
1870	Standard constructor
1871
1872	\param p the Provider associated with this context
1873	*/
1874	KeyStoreEntryContext(Provider *p)
1875	: BasicContext(p, QStringLiteral("keystoreentry"))
1876	{
1877	}
1878
1879	/**
1880	Returns the entry type
1881	*/
1882	virtual KeyStoreEntry::Type type() const = 0;
1883
1884	/**
1885	Returns the entry id
1886
1887	This id must be unique among all other entries in the same store.
1888	*/
1889	virtual QString id() const = 0;
1890
1891	/**
1892	Returns the name of this entry
1893	*/
1894	virtual QString name() const = 0;
1895
1896	/**
1897	Returns the id of the store that contains this entry
1898	*/
1899	virtual QString storeId() const = 0;
1900
1901	/**
1902	Returns the name of the store that contains this entry
1903	*/
1904	virtual QString storeName() const = 0;
1905
1906	/**
1907	Returns true if the private key of this entry is present for use
1908	*/
1909	virtual bool isAvailable() const;
1910
1911	/**
1912	Serialize the information about this entry
1913
1914	This allows the entry object to be restored later, even if the
1915	store that contains it is not present.
1916
1917	\sa KeyStoreListContext::entryPassive()
1918	*/
1919	virtual QString serialize() const = 0;
1920
1921	/**
1922	If this entry is of type KeyStoreEntry::TypeKeyBundle, this
1923	function returns the KeyBundle of the entry
1924	*/
1925	virtual KeyBundle keyBundle() const;
1926
1927	/**
1928	If this entry is of type KeyStoreEntry::TypeCertificate, this
1929	function returns the Certificate of the entry
1930	*/
1931	virtual Certificate certificate() const;
1932
1933	/**
1934	If this entry is of type KeyStoreEntry::TypeCRL, this function
1935	returns the CRL of the entry
1936	*/
1937	virtual CRL crl() const;
1938
1939	/**
1940	If this entry is of type KeyStoreEntry::TypePGPSecretKey, this
1941	function returns the secret PGPKey of the entry
1942	*/
1943	virtual PGPKey pgpSecretKey() const;
1944
1945	/**
1946	If this entry is of type KeyStoreEntry::TypePGPPublicKey or
1947	KeyStoreEntry::TypePGPSecretKey, this function returns the public
1948	PGPKey of the entry
1949	*/
1950	virtual PGPKey pgpPublicKey() const;
1951
1952	/**
1953	Attempt to ensure the private key of this entry is usable and
1954	accessible, potentially prompting the user and/or performing a
1955	login to a token device. Returns true if the entry is now
1956	accessible, or false if the entry cannot be made accessible.
1957
1958	This function is blocking.
1959	*/
1960	virtual bool ensureAccess();
1961	};
1962
1963	/**
1964	\class KeyStoreListContext qcaprovider.h QtCrypto
1965
1966	KeyStore provider
1967
1968	\note This class is part of the provider plugin interface and should not
1969	be used directly by applications. You probably want KeyStore instead.
1970
1971	\ingroup ProviderAPI
1972	*/
1973	class QCA_EXPORT KeyStoreListContext : public Provider::Context
1974	{
1975	Q_OBJECT
1976	public:
1977	/**
1978	Standard constructor
1979
1980	\param p the Provider associated with this context
1981	*/
1982	KeyStoreListContext(Provider *p)
1983	: Provider::Context(p, QStringLiteral("keystorelist"))
1984	{
1985	}
1986
1987	/**
1988	Starts the keystore provider
1989	*/
1990	virtual void start();
1991
1992	/**
1993	Enables or disables update events
1994
1995	The updated() and storeUpdated() signals might not be emitted if
1996	updates are not enabled.
1997
1998	\param enabled whether update notifications are enabled (true) or disabled (false)
1999	*/
2000	virtual void setUpdatesEnabled(bool enabled);
2001
2002	/**
2003	Returns a list of integer context ids, each representing a
2004	keystore instance
2005
2006	If a keystore becomes unavailable and then later becomes
2007	available again (for example, if a smart card is removed and
2008	then the same one is inserted again), the integer context id
2009	must be different than last time.
2010	*/
2011	virtual QList<int> keyStores() = 0;
2012
2013	/**
2014	Returns the type of the specified store, or -1 if the integer
2015	context id is invalid
2016
2017	\param id the id for the store context
2018	*/
2019	virtual KeyStore::Type type(int id) const = 0;
2020
2021	/**
2022	Returns the string id of the store, or an empty string if the
2023	integer context id is invalid
2024
2025	The string id of the store should be unique to a single store, and
2026	it should persist between availability/unavailability. For
2027	example, a smart card that is removed and inserted again should
2028	have the same string id (despite having a new integer context id).
2029
2030	\param id the id for the store context
2031	*/
2032	virtual QString storeId(int id) const = 0;
2033
2034	/**
2035	Returns the friendly name of the store, or an empty string if the
2036	integer context id is invalid
2037
2038	\param id the id for the store context
2039	*/
2040	virtual QString name(int id) const = 0;
2041
2042	/**
2043	Returns true if the store is read-only
2044
2045	If the integer context id is invalid, this function should return
2046	true.
2047
2048	\param id the id for the store context
2049	*/
2050	virtual bool isReadOnly(int id) const;
2051
2052	/**
2053	Returns the types supported by the store, or an empty list if the
2054	integer context id is invalid
2055
2056	This function should return all supported types, even if the store
2057	doesn't actually contain entries for all of the types.
2058
2059	\param id the id for the store context
2060	*/
2061	virtual QList<KeyStoreEntry::Type> entryTypes(int id) const = 0;
2062
2063	/**
2064	Returns the entries of the store, or an empty list if the integer
2065	context id is invalid
2066
2067	The caller is responsible for deleting the returned entry objects.
2068
2069	\param id the id for the store context
2070	*/
2071	virtual QList<KeyStoreEntryContext *> entryList(int id) = 0;
2072
2073	/**
2074	Returns a single entry in the store, if the entry id is already
2075	known. If the entry does not exist, the function returns 0.
2076
2077	The caller is responsible for deleting the returned entry object.
2078
2079	\param id the id for the store context
2080	\param entryId the entry to retrieve
2081	*/
2082	virtual KeyStoreEntryContext *entry(int id, const QString &entryId);
2083
2084	/**
2085	Returns a single entry, created from the serialization string of
2086	a previous entry (using KeyStoreEntryContext::serialize()). If
2087	the serialization string cannot be parsed by this provider, or the
2088	entry cannot otherwise be created, the function returns 0.
2089
2090	The caller is responsible for deleting the returned entry object.
2091
2092	This function must be thread-safe.
2093
2094	\param serialized the serialized data to create the entry from
2095	*/
2096	virtual KeyStoreEntryContext *entryPassive(const QString &serialized);
2097
2098	/**
2099	Write a KeyBundle to the store
2100
2101	Returns the entry id of the new item, or an empty string if there
2102	was an error writing the item.
2103
2104	\param id the id for the store context
2105	\param kb the key bundle to add to the store
2106	*/
2107	virtual QString writeEntry(int id, const KeyBundle &kb);
2108
2109	/**
2110	Write a Certificate to the store
2111
2112	Returns the entry id of the new item, or an empty string if there
2113	was an error writing the item.
2114
2115	\param id the id for the store context
2116	\param cert the certificate to add to the store
2117	*/
2118	virtual QString writeEntry(int id, const Certificate &cert);
2119
2120	/**
2121	Write a CRL to the store
2122
2123	Returns the entry id of the new item, or an empty string if there
2124	was an error writing the item.
2125
2126	\param id the id for the store context
2127	\param crl the revocation list to add to the store
2128	*/
2129	virtual QString writeEntry(int id, const CRL &crl);
2130
2131	/**
2132	Write a PGPKey to the store
2133
2134	Returns the entry id of the new item, or an empty string if there
2135	was an error writing the item.
2136
2137	\param id the id for the store context
2138	\param key the PGP key to add to the store
2139	*/
2140	virtual QString writeEntry(int id, const PGPKey &key);
2141
2142	/**
2143	Remove an entry from the store
2144
2145	Returns true if the entry is successfully removed, otherwise
2146	false.
2147
2148	\param id the id for the store context
2149	\param entryId the entry to remove from the store
2150	*/
2151	virtual bool removeEntry(int id, const QString &entryId);
2152
2153	Q_SIGNALS:
2154	/**
2155	Emit this when the provider is busy looking for keystores. The
2156	provider goes into a busy state when it has reason to believe
2157	there are keystores present, but it still needs to check or query
2158	some devices to see for sure.
2159
2160	For example, if a smart card is inserted, then the provider may
2161	immediately go into a busy state upon detecting the insert.
2162	However, it may take some seconds before the smart card
2163	information can be queried and reported by the provider. Once
2164	the card is queried successfully, the provider would leave the
2165	busy state and report the new keystore.
2166
2167	When this object is first started with start(), it is assumed to
2168	be in the busy state, so there is no need to emit this signal at
2169	the beginning.
2170	*/
2171	void busyStart();
2172
2173	/**
2174	Emit this to leave the busy state
2175
2176	When this object is first started with start(), it is assumed to
2177	be in the busy state. You must emit busyEnd() at some point, or
2178	QCA will never ask you about keystores.
2179	*/
2180	void busyEnd();
2181
2182	/**
2183	Indicates the list of keystores has changed, and that QCA should
2184	call keyStores() to obtain the latest list
2185	*/
2186	void updated();
2187
2188	/**
2189	Emitted when there is diagnostic text to report
2190
2191	\param str the diagnostic text
2192	*/
2193	void diagnosticText(const QString &str);
2194
2195	/**
2196	Indicates that the entry list of a keystore has changed (entries
2197	added, removed, or modified)
2198
2199	\param id the id of the key store that has changed
2200	*/
2201	void storeUpdated(int id);
2202	};
2203
2204	/**
2205	\class TLSSessionContext qcaprovider.h QtCrypto
2206
2207	TLS "session" provider
2208
2209	\note This class is part of the provider plugin interface and should not
2210	be used directly by applications. You probably want TLSSession instead.
2211
2212	\ingroup ProviderAPI
2213	*/
2214	class QCA_EXPORT TLSSessionContext : public BasicContext
2215	{
2216	Q_OBJECT
2217	public:
2218	/**
2219	Standard constructor
2220
2221	\param p the Provider associated with this context
2222	*/
2223	TLSSessionContext(Provider *p)
2224	: BasicContext(p, QStringLiteral("tlssession"))
2225	{
2226	}
2227	};
2228
2229	/**
2230	\class TLSContext qcaprovider.h QtCrypto
2231
2232	TLS provider
2233
2234	\note This class is part of the provider plugin interface and should not
2235	be used directly by applications. You probably want TLS instead.
2236
2237	\ingroup ProviderAPI
2238	*/
2239	class QCA_EXPORT TLSContext : public Provider::Context
2240	{
2241	Q_OBJECT
2242	public:
2243	/**
2244	\class QCA::TLSContext::SessionInfo qcaprovider.h QtCrypto
2245
2246	Information about an active TLS connection
2247
2248	For efficiency and simplicity, the members are directly accessed.
2249
2250	\ingroup ProviderAPI
2251	*/
2252	class SessionInfo
2253	{
2254	public:
2255	/**
2256	True if the TLS connection is compressed, otherwise false
2257	*/
2258	bool isCompressed;
2259
2260	/**
2261	The TLS protocol version being used for this connection
2262	*/
2263	TLS::Version version;
2264
2265	/**
2266	The cipher suite being used for this connection
2267
2268	\sa TLSContext::supportedCipherSuites()
2269	*/
2270	QString cipherSuite;
2271
2272	/**
2273	The bit size of the cipher used for this connection
2274	*/
2275	int cipherBits;
2276
2277	/**
2278	The maximum bit size possible of the cipher used for this
2279	connection
2280	*/
2281	int cipherMaxBits;
2282
2283	/**
2284	Pointer to the id of this TLS session, for use with
2285	resuming
2286	*/
2287	TLSSessionContext *id;
2288	};
2289
2290	/**
2291	Result of a TLS operation
2292	*/
2293	enum Result
2294	{
2295	Success, ///< Operation completed
2296	Error, ///< Operation failed
2297	Continue ///< More data needed to complete operation
2298	};
2299
2300	/**
2301	Standard constructor
2302
2303	\param p the Provider associated with this context
2304	\param type the name of the type of feature that supported by this context
2305	*/
2306	TLSContext(Provider *p, const QString &type)
2307	: Provider::Context(p, type)
2308	{
2309	}
2310
2311	/**
2312	Reset the object to its initial state
2313	*/
2314	virtual void reset() = 0;
2315
2316	/**
2317	Returns a list of supported cipher suites for the specified
2318	SSL/TLS version. The cipher suites are specified as strings, for
2319	example: "TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA" (without quotes).
2320
2321	\param version the version of TLS to search for
2322	*/
2323	virtual QStringList supportedCipherSuites(const TLS::Version &version) const = 0;
2324
2325	/**
2326	Returns true if the provider supports compression
2327	*/
2328	virtual bool canCompress() const = 0;
2329
2330	/**
2331	Returns true if the provider supports server name indication
2332	*/
2333	virtual bool canSetHostName() const = 0;
2334
2335	/**
2336	Returns the maximum SSF supported by this provider
2337	*/
2338	virtual int maxSSF() const = 0;
2339
2340	/**
2341	Configure a new session
2342
2343	This function will be called before any other configuration
2344	functions.
2345
2346	\param serverMode whether to operate as a server (true) or client (false)
2347	\param hostName the hostname to use
2348	\param compress whether to compress (true) or not (false)
2349	*/
2350	virtual void setup(bool serverMode, const QString &hostName, bool compress) = 0;
2351
2352	/**
2353	Set the constraints of the session using SSF values
2354
2355	This function will be called before start().
2356
2357	\param minSSF the minimum strength factor that is acceptable
2358	\param maxSSF the maximum strength factor that is acceptable
2359	*/
2360	virtual void setConstraints(int minSSF, int maxSSF) = 0;
2361
2362	/**
2363	\overload
2364
2365	Set the constraints of the session using a cipher suite list
2366
2367	This function will be called before start().
2368
2369	\param cipherSuiteList the list of cipher suites that may be used for
2370	this session.
2371
2372	\sa supportedCipherSuites
2373	*/
2374	virtual void setConstraints(const QStringList &cipherSuiteList) = 0;
2375
2376	/**
2377	Set the list of trusted certificates
2378
2379	This function may be called at any time.
2380
2381	\param trusted the trusted certificates and CRLs to be used.
2382	*/
2383	virtual void setTrustedCertificates(const CertificateCollection &trusted) = 0;
2384
2385	/**
2386	Set the list of acceptable issuers
2387
2388	This function may be called at any time.
2389
2390	This function is for server mode only.
2391
2392	\param issuerList the list of issuers that may be used
2393	*/
2394	virtual void setIssuerList(const QList<CertificateInfoOrdered> &issuerList) = 0;
2395
2396	/**
2397	Set the local certificate
2398
2399	This function may be called at any time.
2400
2401	\param cert the certificate and associated trust chain
2402	\param key the private key for the local certificate
2403	*/
2404	virtual void setCertificate(const CertificateChain &cert, const PrivateKey &key) = 0;
2405
2406	/**
2407	Set the TLS session id, for session resuming
2408
2409	This function will be called before start().
2410
2411	\param id the session identification
2412	*/
2413	virtual void setSessionId(const TLSSessionContext &id) = 0;
2414
2415	/**
2416	Sets the session to the shutdown state.
2417
2418	The actual shutdown operation will happen at a future call to
2419	update().
2420
2421	This function is for normal TLS only (not DTLS).
2422	*/
2423	virtual void shutdown() = 0;
2424
2425	/**
2426	Set the maximum transmission unit size
2427
2428	This function is for DTLS only.
2429
2430	\param size the maximum number of bytes in a datagram
2431	*/
2432	virtual void setMTU(int size);
2433
2434	/**
2435	Begins the session, starting with the handshake
2436
2437	This function returns immediately, and completion is signaled with
2438	the resultsReady() signal.
2439
2440	On completion, the result() function will return Success if the
2441	TLS session is able to begin, or Error if there is a failure to
2442	initialize the TLS subsystem. If successful, the session is now
2443	in the handshake state, and update() will be called repeatedly
2444	until the session ends.
2445	*/
2446	virtual void start() = 0;
2447
2448	/**
2449	Performs one iteration of the TLS session processing
2450
2451	This function returns immediately, and completion is signaled with
2452	the resultsReady() signal.
2453
2454	If the session is in a handshake state, result() and to_net() will
2455	be valid. If result() is Success, then the session is now in the
2456	connected state.
2457
2458	If the session is in a shutdown state, result() and to_net() will
2459	be valid. If result() is Success, then the session has ended.
2460
2461	If the session is in a connected state, result(), to_net(),
2462	encoded(), to_app(), and eof() are valid. The result() function
2463	will return Success or Error. Note that eof() does not apply
2464	to DTLS.
2465
2466	For DTLS, this function operates with single packets. Many
2467	update() operations must be performed repeatedly to exchange
2468	multiple packets.
2469
2470	\param from_net the data from the "other side" of the connection
2471	\param from_app the data from the application of the protocol
2472	*/
2473	virtual void update(const QByteArray &from_net, const QByteArray &from_app) = 0;
2474
2475	/**
2476	Waits for a start() or update() operation to complete. In this
2477	case, the resultsReady() signal is not emitted. Returns true if
2478	the operation completed or false if this function times out.
2479
2480	This function is blocking.
2481
2482	\param msecs number of milliseconds to wait (-1 to wait forever)
2483	*/
2484	virtual bool waitForResultsReady(int msecs) = 0;
2485
2486	/**
2487	Returns the result code of an operation
2488	*/
2489	virtual Result result() const = 0;
2490
2491	/**
2492	Returns data that should be sent across the network
2493	*/
2494	virtual QByteArray to_net() = 0;
2495
2496	/**
2497	Returns the number of bytes of plaintext data that is encoded
2498	inside of to_net()
2499	*/
2500	virtual int encoded() const = 0;
2501
2502	/**
2503	Returns data that is decoded from the network and should be
2504	processed by the application
2505	*/
2506	virtual QByteArray to_app() = 0;
2507
2508	/**
2509	Returns true if the peer has closed the stream
2510	*/
2511	virtual bool eof() const = 0;
2512
2513	/**
2514	Returns true if the TLS client hello has been received
2515
2516	This is only valid if a handshake is in progress or
2517	completed.
2518	*/
2519	virtual bool clientHelloReceived() const = 0;
2520
2521	/**
2522	Returns true if the TLS server hello has been received
2523
2524	This is only valid if a handshake is in progress or completed.
2525	*/
2526	virtual bool serverHelloReceived() const = 0;
2527
2528	/**
2529	Returns the host name sent by the client using server name
2530	indication (server mode only)
2531
2532	This is only valid if a handshake is in progress or completed.
2533	*/
2534	virtual QString hostName() const = 0;
2535
2536	/**
2537	Returns true if the peer is requesting a certificate
2538
2539	This is only valid if a handshake is in progress or completed.
2540	*/
2541	virtual bool certificateRequested() const = 0;
2542
2543	/**
2544	Returns the issuer list sent by the server (client mode only)
2545
2546	This is only valid if a handshake is in progress or completed.
2547	*/
2548	virtual QList<CertificateInfoOrdered> issuerList() const = 0;
2549
2550	/**
2551	Returns the QCA::Validity of the peer certificate
2552
2553	This is only valid if a handshake is completed.
2554	*/
2555	virtual Validity peerCertificateValidity() const = 0;
2556
2557	/**
2558	Returns the peer certificate chain
2559
2560	This is only valid if a handshake is completed.
2561	*/
2562	virtual CertificateChain peerCertificateChain() const = 0;
2563
2564	/**
2565	Returns information about the active TLS session
2566
2567	This is only valid if a handshake is completed.
2568	*/
2569	virtual SessionInfo sessionInfo() const = 0;
2570
2571	/**
2572	Returns any unprocessed network input data
2573
2574	This is only valid after a successful shutdown.
2575	*/
2576	virtual QByteArray unprocessed() = 0;
2577
2578	Q_SIGNALS:
2579	/**
2580	Emit this when a start() or update() operation has completed.
2581	*/
2582	void resultsReady();
2583
2584	/**
2585	Emit this to force the application to call update(), even with
2586	empty arguments.
2587	*/
2588	void dtlsTimeout();
2589	};
2590
2591	/**
2592	\class SASLContext qcaprovider.h QtCrypto
2593
2594	SASL provider
2595
2596	\note This class is part of the provider plugin interface and should not
2597	be used directly by applications. You probably want SASL instead.
2598
2599	\ingroup ProviderAPI
2600	*/
2601	class QCA_EXPORT SASLContext : public Provider::Context
2602	{
2603	Q_OBJECT
2604	public:
2605	/**
2606	\class QCA::SASLContext::HostPort qcaprovider.h QtCrypto
2607
2608	Convenience class to hold an IP address and an associated port
2609
2610	For efficiency and simplicity, the members are directly accessed.
2611
2612	\ingroup ProviderAPI
2613	*/
2614	class HostPort
2615	{
2616	public:
2617	/**
2618	The IP address
2619	*/
2620	QString addr;
2621
2622	/**
2623	The port
2624	*/
2625	quint16 port;
2626	};
2627
2628	/**
2629	Result of a SASL operation
2630	*/
2631	enum Result
2632	{
2633	Success, ///< Operation completed
2634	Error, ///< Operation failed
2635	Params, ///< Parameters are needed to complete authentication
2636	AuthCheck, ///< Client login can be inspected (server only)
2637	Continue ///< More steps needed to complete authentication
2638	};
2639
2640	/**
2641	Standard constructor
2642
2643	\param p the Provider associated with this context
2644	*/
2645	SASLContext(Provider *p)
2646	: Provider::Context(p, QStringLiteral("sasl"))
2647	{
2648	}
2649
2650	/**
2651	Reset the object to its initial state
2652	*/
2653	virtual void reset() = 0;
2654
2655	/**
2656	Configure a new session
2657
2658	This function will be called before any other configuration
2659	functions.
2660
2661	\param service the name of the network service being provided by
2662	this application, which can be used by the SASL system for policy
2663	control. Examples: "imap", "xmpp"
2664	\param host the hostname that the application is interacting with
2665	or as
2666	\param local pointer to a HostPort representing the local end of a
2667	network socket, or 0 if this information is unknown or not
2668	available
2669	\param remote pointer to a HostPort representing the peer end of a
2670	network socket, or 0 if this information is unknown or not
2671	available
2672	\param ext_id the id to be used for SASL EXTERNAL (client only)
2673	\param ext_ssf the SSF of the external authentication channel
2674	(client only)
2675	*/
2676	virtual void setup(const QString &service,
2677	const QString &host,
2678	const HostPort *local,
2679	const HostPort *remote,
2680	const QString &ext_id,
2681	int ext_ssf) = 0;
2682
2683	/**
2684	Set the constraints of the session using SSF values
2685
2686	This function will be called before startClient() or
2687	startServer().
2688
2689	\param f the flags to use
2690	\param minSSF the minimum strength factor that is acceptable
2691	\param maxSSF the maximum strength factor that is acceptable
2692	*/
2693	virtual void setConstraints(SASL::AuthFlags f, int minSSF, int maxSSF) = 0;
2694
2695	/**
2696	Begins the session in client mode, starting with the
2697	authentication
2698
2699	This function returns immediately, and completion is signaled with
2700	the resultsReady() signal.
2701
2702	On completion, result(), mech(), haveClientInit(), and stepData()
2703	will be valid. If result() is Success, then the session is now in
2704	the connected state.
2705
2706	\param mechlist the list of mechanisms
2707	\param allowClientSendFirst whether the client sends first (true) or the server
2708	sends first (false)
2709	*/
2710	virtual void startClient(const QStringList &mechlist, bool allowClientSendFirst) = 0;
2711
2712	/**
2713	Begins the session in server mode, starting with the
2714	authentication
2715
2716	This function returns immediately, and completion is signaled with
2717	the resultsReady() signal.
2718
2719	On completion, result() and mechlist() will be valid. The
2720	result() function will return Success or Error. If the result is
2721	Success, then serverFirstStep() will be called next.
2722
2723	\param realm the realm to authenticate in
2724	\param disableServerSendLast whether the client sends first (true)
2725	or the server sends first (false)
2726	*/
2727	virtual void startServer(const QString &realm, bool disableServerSendLast) = 0;
2728
2729	/**
2730	Finishes server startup
2731
2732	This function returns immediately, and completion is signaled with
2733	the resultsReady() signal.
2734
2735	On completion, result() and stepData() will be valid. If result()
2736	is Success, then the session is now in the connected state.
2737
2738	\param mech the mechanism to use
2739	\param clientInit initial data from the client, or 0 if there is
2740	no such data
2741	*/
2742	virtual void serverFirstStep(const QString &mech, const QByteArray *clientInit) = 0;
2743
2744	/**
2745	Perform another step of the SASL authentication
2746
2747	This function returns immediately, and completion is signaled with
2748	the resultsReady() signal.
2749
2750	On completion, result() and stepData() will be valid.
2751
2752	\param from_net the data from the "other side" of the protocol
2753	to be used for the next step.
2754	*/
2755	virtual void nextStep(const QByteArray &from_net) = 0;
2756
2757	/**
2758	Attempt the most recent operation again. This is used if the
2759	result() of an operation is Params or AuthCheck.
2760
2761	This function returns immediately, and completion is signaled with
2762	the resultsReady() signal.
2763
2764	On completion, result() and stepData() will be valid.
2765	*/
2766	virtual void tryAgain() = 0;
2767
2768	/**
2769	Performs one iteration of the SASL security layer processing
2770
2771	This function returns immediately, and completion is signaled with
2772	the resultsReady() signal.
2773
2774	On completion, result(), to_net(), encoded(), and to_app() will be
2775	valid. The result() function will return Success or Error.
2776
2777	\param from_net the data from the "other side" of the protocol
2778	\param from_app the data from the application of the protocol
2779	*/
2780	virtual void update(const QByteArray &from_net, const QByteArray &from_app) = 0;
2781
2782	/**
2783	Waits for a startClient(), startServer(), serverFirstStep(),
2784	nextStep(), tryAgain(), or update() operation to complete. In
2785	this case, the resultsReady() signal is not emitted. Returns true
2786	if the operation completed or false if this function times out.
2787
2788	This function is blocking.
2789
2790	\param msecs number of milliseconds to wait (-1 to wait forever)
2791	*/
2792	virtual bool waitForResultsReady(int msecs) = 0;
2793
2794	/**
2795	Returns the result code of an operation
2796	*/
2797	virtual Result result() const = 0;
2798
2799	/**
2800	Returns the mechanism list (server mode only)
2801	*/
2802	virtual QStringList mechlist() const = 0;
2803
2804	/**
2805	Returns the mechanism selected
2806	*/
2807	virtual QString mech() const = 0;
2808
2809	/**
2810	Returns true if the client has initialization data
2811	*/
2812	virtual bool haveClientInit() const = 0;
2813
2814	/**
2815	Returns an authentication payload for to be transmitted over the
2816	network
2817	*/
2818	virtual QByteArray stepData() const = 0;
2819
2820	/**
2821	Returns data that should be sent across the network (for the
2822	security layer)
2823	*/
2824	virtual QByteArray to_net() = 0;
2825
2826	/**
2827	Returns the number of bytes of plaintext data that is encoded
2828	inside of to_net()
2829	*/
2830	virtual int encoded() const = 0;
2831
2832	/**
2833	Returns data that is decoded from the network and should be
2834	processed by the application
2835	*/
2836	virtual QByteArray to_app() = 0;
2837
2838	/**
2839	Returns the SSF of the active SASL session
2840
2841	This is only valid after authentication success.
2842	*/
2843	virtual int ssf() const = 0;
2844
2845	/**
2846	Returns the reason for failure, if the authentication was not
2847	successful.
2848
2849	This is only valid after authentication failure.
2850	*/
2851	virtual SASL::AuthCondition authCondition() const = 0;
2852
2853	/**
2854	Returns the needed/optional client parameters
2855
2856	This is only valid after receiving the Params result code.
2857	*/
2858	virtual SASL::Params clientParams() const = 0;
2859
2860	/**
2861	Set some of the client parameters (pass 0 to not set a field)
2862
2863	\param user the user name
2864	\param authzid the authorization name / role
2865	\param pass the password
2866	\param realm the realm to authenticate in
2867	*/
2868	virtual void
2869	setClientParams(const QString *user, const QString *authzid, const SecureArray *pass, const QString *realm) = 0;
2870
2871	/**
2872	Returns the realm list (client mode only)
2873
2874	This is only valid after receiving the Params result code and
2875	SASL::Params::canSendRealm is set to true.
2876	*/
2877	virtual QStringList realmlist() const = 0;
2878
2879	/**
2880	Returns the username attempting to authenticate (server mode only)
2881
2882	This is only valid after receiving the AuthCheck result code.
2883	*/
2884	virtual QString username() const = 0;
2885
2886	/**
2887	Returns the authzid attempting to authorize (server mode only)
2888
2889	This is only valid after receiving the AuthCheck result code.
2890	*/
2891	virtual QString authzid() const = 0;
2892
2893	Q_SIGNALS:
2894	/**
2895	Emit this when a startClient(), startServer(), serverFirstStep(),
2896	nextStep(), tryAgain(), or update() operation has completed.
2897	*/
2898	void resultsReady();
2899	};
2900
2901	/**
2902	\class MessageContext qcaprovider.h QtCrypto
2903
2904	SecureMessage provider
2905
2906	\note This class is part of the provider plugin interface and should not
2907	be used directly by applications. You probably want SecureMessage
2908	instead.
2909
2910	\ingroup ProviderAPI
2911	*/
2912	class QCA_EXPORT MessageContext : public Provider::Context
2913	{
2914	Q_OBJECT
2915	public:
2916	/**
2917	The type of operation being performed
2918	*/
2919	enum Operation
2920	{
2921	Encrypt, ///< Encrypt operation
2922	Decrypt, ///< Decrypt (or Decrypt and Verify) operation
2923	Sign, ///< Sign operation
2924	Verify, ///< Verify operation
2925	SignAndEncrypt ///< Sign and Encrypt operation
2926	};
2927
2928	/**
2929	Standard constructor
2930
2931	\param p the Provider associated with this context
2932	\param type the name of the type of secure message to be created
2933	*/
2934	MessageContext(Provider *p, const QString &type)
2935	: Provider::Context(p, type)
2936	{
2937	}
2938
2939	/**
2940	Returns true if the provider supports multiple signers for
2941	signature creation or signature verification
2942	*/
2943	virtual bool canSignMultiple() const = 0;
2944
2945	/**
2946	The type of secure message (e.g. PGP or CMS)
2947	*/
2948	virtual SecureMessage::Type type() const = 0;
2949
2950	/**
2951	Reset the object to its initial state
2952	*/
2953	virtual void reset() = 0;
2954
2955	/**
2956	Configure a new encrypting operation
2957
2958	\param keys the keys to be used for encryption.
2959	*/
2960	virtual void setupEncrypt(const SecureMessageKeyList &keys) = 0;
2961
2962	/**
2963	Configure a new signing operation
2964
2965	\param keys the keys to use for signing
2966	\param m the mode to sign in
2967	\param bundleSigner whether to bundle the signing keys (true) or not (false)
2968	\param smime whether to use smime format (true) or not (false)
2969	*/
2970	virtual void
2971	setupSign(const SecureMessageKeyList &keys, SecureMessage::SignMode m, bool bundleSigner, bool smime) = 0;
2972
2973	/**
2974	Configure a new verify operation
2975
2976	\param detachedSig the detached signature to use (if applicable) for verification
2977	*/
2978	virtual void setupVerify(const QByteArray &detachedSig) = 0;
2979
2980	/**
2981	Begins the secure message operation
2982
2983	This function returns immediately.
2984
2985	If there is input data, update() will be called (potentially
2986	repeatedly) afterwards. Emit updated() if there is data to
2987	read, if input data has been accepted, or if the operation has
2988	finished.
2989
2990	\param f the format of the message to be produced
2991	\param op the operation to be performed
2992	*/
2993	virtual void start(SecureMessage::Format f, Operation op) = 0;
2994
2995	/**
2996	Provide input to the message operation
2997
2998	\param in the data to use for the message operation
2999	*/
3000	virtual void update(const QByteArray &in) = 0;
3001
3002	/**
3003	Extract output from the message operation
3004	*/
3005	virtual QByteArray read() = 0;
3006
3007	/**
3008	Returns the number of input bytes accepted since the last call to
3009	update()
3010	*/
3011	virtual int written() = 0;
3012
3013	/**
3014	Indicates the end of input
3015	*/
3016	virtual void end() = 0;
3017
3018	/**
3019	Returns true if the operation has finished, otherwise false
3020	*/
3021	virtual bool finished() const = 0;
3022
3023	/**
3024	Waits for the secure message operation to complete. In this case,
3025	the updated() signal is not emitted. Returns true if the
3026	operation completed or false if this function times out.
3027
3028	This function is blocking.
3029
3030	\param msecs number of milliseconds to wait (-1 to wait forever)
3031	*/
3032	virtual bool waitForFinished(int msecs) = 0;
3033
3034	/**
3035	Returns true if the operation was successful
3036
3037	This is only valid if the operation has finished.
3038	*/
3039	virtual bool success() const = 0;
3040
3041	/**
3042	Returns the reason for failure, if the operation was not
3043	successful
3044
3045	This is only valid if the operation has finished.
3046	*/
3047	virtual SecureMessage::Error errorCode() const = 0;
3048
3049	/**
3050	Returns the signature, in the case of a detached signature
3051	operation
3052
3053	This is only valid if the operation has finished.
3054	*/
3055	virtual QByteArray signature() const = 0;
3056
3057	/**
3058	Returns the name of the hash used to generate the signature, in
3059	the case of a signature operation
3060
3061	This is only valid if the operation has finished.
3062	*/
3063	virtual QString hashName() const = 0;
3064
3065	/**
3066	Returns a list of signatures, in the case of a verify or decrypt
3067	and verify operation
3068
3069	This is only valid if the operation has finished.
3070	*/
3071	virtual SecureMessageSignatureList signers() const = 0;
3072
3073	/**
3074	Returns any diagnostic text for the operation, potentially useful
3075	to show the user in the event the operation is unsuccessful. For
3076	example, this could be the stderr output of gpg.
3077
3078	This is only valid if the operation has finished.
3079	*/
3080	virtual QString diagnosticText() const;
3081
3082	Q_SIGNALS:
3083	/**
3084	Emitted when there is data to read, if input data has been
3085	accepted, or if the operation has finished
3086	*/
3087	void updated();
3088	};
3089
3090	/**
3091	\class SMSContext qcaprovider.h QtCrypto
3092
3093	SecureMessageSystem provider
3094
3095	\note This class is part of the provider plugin interface and should not
3096	be used directly by applications. You probably want SecureMessageSystem
3097	instead.
3098
3099	\ingroup ProviderAPI
3100	*/
3101	class QCA_EXPORT SMSContext : public BasicContext
3102	{
3103	Q_OBJECT
3104	public:
3105	/**
3106	Standard constructor
3107
3108	\param p the provider associated with this context
3109	\param type the name of the type of secure message system
3110	*/
3111	SMSContext(Provider *p, const QString &type)
3112	: BasicContext(p, type)
3113	{
3114	}
3115
3116	/**
3117	Set the trusted certificates and for this secure message system,
3118	to be used for validation
3119
3120	The collection may also contain CRLs.
3121
3122	This function is only valid for CMS.
3123
3124	\param trusted a set of trusted certificates and CRLs.
3125	*/
3126	virtual void setTrustedCertificates(const CertificateCollection &trusted);
3127
3128	/**
3129	Set the untrusted certificates and CRLs for this secure message
3130	system, to be used for validation
3131
3132	This function is only valid for CMS.
3133
3134	\param untrusted a set of untrusted certificates and CRLs.
3135	*/
3136	virtual void setUntrustedCertificates(const CertificateCollection &untrusted);
3137
3138	/**
3139	Set the private keys for this secure message system, to be used
3140	for decryption
3141
3142	This function is only valid for CMS.
3143
3144	\param keys the keys to be used for decryption
3145	*/
3146	virtual void setPrivateKeys(const QList<SecureMessageKey> &keys);
3147
3148	/**
3149	Create a new message object for this system. The caller is
3150	responsible for deleting it.
3151	*/
3152	virtual MessageContext *createMessage() = 0;
3153	};
3154
3155	}
3156	#endif
3157
3158	#endif
3159