QCA

qcaprovider.h
Go to the documentation of this file.
1 /*
2  * qcaprovider.h - QCA Plugin API
3  * Copyright (C) 2003-2007 Justin Karneges <[email protected]>
4  * Copyright (C) 2004,2005 Brad Hards <[email protected]>
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
1141 
1142  /**
1143  The time the certificate expires
1144 
1145  This field is for certificates only.
1146  */
1148 
1149  /**
1150  The subject information
1151  */
1153 
1154  /**
1155  The issuer information
1156 
1157  This field is for certificates only.
1158  */
1160 
1161  /**
1162  The constraints
1163  */
1165 
1166  /**
1167  The policies
1168  */
1170 
1171  /**
1172  A list of URIs for CRLs
1173 
1174  This field is for certificates only.
1175  */
1177 
1178  /**
1179  A list of URIs for issuer certificates
1180 
1181  This field is for certificates only.
1182  */
1184 
1185  /**
1186  A list of URIs for OCSP services
1187 
1188  This field is for certificates only.
1189  */
1191 
1192  /**
1193  The certificate serial number
1194 
1195  This field is for certificates only.
1196  */
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  */
1211 
1212  /**
1213  The path limit
1214  */
1216 
1217  /**
1218  The signature data
1219  */
1221 
1222  /**
1223  The signature algorithm used to create the signature
1224  */
1226 
1227  /**
1228  The subject id
1229 
1230  This field is for certificates only.
1231  */
1233 
1234  /**
1235  The issuer id
1236 
1237  This field is for certificates only.
1238  */
1240 
1241  /**
1242  The SPKAC challenge value
1243 
1244  This field is for certificate requests only.
1245  */
1247 
1248  /**
1249  The format used for the certificate request
1250 
1251  This field is for certificate requests only.
1252  */
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  */
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  */
1285 
1286  /**
1287  The time this CRL expires, and the next CRL should be fetched
1288  */
1290 
1291  /**
1292  The revoked entries
1293  */
1295 
1296  /**
1297  The signature data of the CRL
1298  */
1300 
1301  /**
1302  The signature algorithm used by the issuer to sign the CRL
1303  */
1305 
1306  /**
1307  The issuer id
1308  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
1752 
1753  /**
1754  List of user id strings for the key, the first one being the
1755  primary user id
1756  */
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  */
1768 
1769  /**
1770  The time the key expires
1771  */
1773 
1774  /**
1775  The hex fingerprint of the key
1776 
1777  The format is all lowercase with no spaces.
1778  */
1780 
1781  /**
1782  True if this key is in a keyring (and thus usable), otherwise
1783  false
1784  */
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  */
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  */
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  */
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  */
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  */
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  */
2253  {
2254  public:
2255  /**
2256  True if the TLS connection is compressed, otherwise false
2257  */
2259 
2260  /**
2261  The TLS protocol version being used for this connection
2262  */
2264 
2265  /**
2266  The cipher suite being used for this connection
2267 
2268  \sa TLSContext::supportedCipherSuites()
2269  */
2271 
2272  /**
2273  The bit size of the cipher used for this connection
2274  */
2276 
2277  /**
2278  The maximum bit size possible of the cipher used for this
2279  connection
2280  */
2282 
2283  /**
2284  Pointer to the id of this TLS session, for use with
2285  resuming
2286  */
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  */
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  */
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  */
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  */
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
@ AuthCheck
Client login can be inspected (server only)
Definition: qcaprovider.h:2636
QByteArray sig
The signature data.
Definition: qcaprovider.h:1220
Direction
Direction settings for symmetric algorithms.
Definition: qca_core.h:140
MessageContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:2934
QString challenge
The SPKAC challenge value.
Definition: qcaprovider.h:1246
CertificateInfoOrdered subject
The subject information.
Definition: qcaprovider.h:1152
CertificateInfoOrdered issuer
The issuer information.
Definition: qcaprovider.h:1159
QList< CRLEntry > revoked
The revoked entries.
Definition: qcaprovider.h:1294
QDateTime end
The time the certificate expires.
Definition: qcaprovider.h:1147
KeyLength anyKeyLength() const
Returns a KeyLength that supports any length.
Definition: qcaprovider.h:341
Error
Errors for secure messages.
SignatureFormat
Signature formats (DSA only)
Definition: qca_publickey.h:92
DHContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:838
QStringList policies
The policies.
Definition: qcaprovider.h:1169
CAContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1611
QDateTime expirationDate
The time the key expires.
Definition: qcaprovider.h:1772
Q_SCRIPTABLE Q_NOREPLY void start()
SMSContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:3111
KeyStoreEntryContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1874
KDFContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:371
InfoContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:121
PGPKeyContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1813
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:41
DLGroupContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:463
@ Params
Parameters are needed to complete authentication.
Definition: qcaprovider.h:2635
Version
Version of TLS or SSL.
TLSSessionContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:2223
Type
The type of entry in the KeyStore.
Definition: qca_keystore.h:146
QStringList crlLocations
A list of URIs for CRLs.
Definition: qcaprovider.h:1176
TLS::Version version
The TLS protocol version being used for this connection.
Definition: qcaprovider.h:2263
CertContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1333
SignatureAlgorithm sigalgo
The signature algorithm used by the issuer to sign the CRL.
Definition: qcaprovider.h:1304
QByteArray issuerId
The issuer id.
Definition: qcaprovider.h:1239
SignatureAlgorithm
Signature algorithm variants.
Definition: qca_publickey.h:73
MACContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:306
PKCS12Context(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1692
bool isCA
True if the certificate is a CA or the certificate request is requesting to be a CA,...
Definition: qcaprovider.h:1203
QString fingerprint
The hex fingerprint of the key.
Definition: qcaprovider.h:1779
bool isSecret
True if this key is a secret key, otherwise false.
Definition: qcaprovider.h:1762
CertificateRequestFormat
Certificate Request Format.
Definition: qca_cert.h:53
@ Success
Operation completed.
Definition: qcaprovider.h:2295
CipherContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:240
@ Decrypt
Decrypt (or Decrypt and Verify) operation.
Definition: qcaprovider.h:2922
EncryptionAlgorithm
Encryption algorithms.
Definition: qca_publickey.h:54
RSAContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:675
QByteArray sig
The signature data of the CRL.
Definition: qcaprovider.h:1299
bool isCompressed
True if the TLS connection is compressed, otherwise false.
Definition: qcaprovider.h:2258
CRLContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1521
Operation
The type of operation being performed.
Definition: qcaprovider.h:2919
int pathLimit
The path limit.
Definition: qcaprovider.h:1215
TLSSessionContext * id
Pointer to the id of this TLS session, for use with resuming.
Definition: qcaprovider.h:2287
QStringList userIds
List of user id strings for the key, the first one being the primary user id.
Definition: qcaprovider.h:1757
@ Encrypt
Encrypt operation.
Definition: qcaprovider.h:2921
KeyStoreListContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1982
Format
Formats for secure messages.
@ Sign
Sign operation.
Definition: qcaprovider.h:2923
CertificateRequestFormat format
The format used for the certificate request.
Definition: qcaprovider.h:1253
@ Error
Operation failed.
Definition: qcaprovider.h:2634
bool inKeyring
True if this key is in a keyring (and thus usable), otherwise false.
Definition: qcaprovider.h:1785
RandomContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:161
UsageMode
Specify the intended usage of a certificate.
Definition: qca_cert.h:482
HKDFContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:425
Type
The type of secure message.
HashContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:194
Type
Types of public key cryptography keys supported by QCA.
int cipherMaxBits
The maximum bit size possible of the cipher used for this connection.
Definition: qcaprovider.h:2281
QDateTime start
The time the certificate becomes valid (often the time of create)
Definition: qcaprovider.h:1140
int cipherBits
The bit size of the cipher used for this connection.
Definition: qcaprovider.h:2275
TLSContext(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:2306
ScriptableExtension * host() const
QDateTime creationDate
The time the key was created.
Definition: qcaprovider.h:1767
ValidateFlags
The conditions to validate for a certificate.
Definition: qca_cert.h:516
bool isSelfSigned
True if the certificate is self-signed.
Definition: qcaprovider.h:1210
ConvertResult
Return value from a format conversion.
SignatureAlgorithm sigalgo
The signature algorithm used to create the signature.
Definition: qcaprovider.h:1225
PBEAlgorithm
Password-based encryption.
AuthCondition
Possible authentication error states.
SASLContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:2645
Constraints constraints
The constraints.
Definition: qcaprovider.h:1164
CertCollectionContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1559
QByteArray subjectId
The subject id.
Definition: qcaprovider.h:1232
AuthFlags
Authentication requirement flag values.
QStringList ocspLocations
A list of URIs for OCSP services.
Definition: qcaprovider.h:1190
QString keyId
The key id.
Definition: qcaprovider.h:1751
Type
The type of keystore.
Definition: qca_keystore.h:423
QDateTime thisUpdate
The time this CRL was created.
Definition: qcaprovider.h:1284
CSRContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:1437
int version
The X.509 certificate version, usually 3.
Definition: qcaprovider.h:1133
virtual ~QCAPlugin()
Destructs the object.
Definition: qcaprovider.h:88
CertificateInfoOrdered issuer
The issuer information of the CRL.
Definition: qcaprovider.h:1274
bool isTrusted
True if this key is trusted (e.g.
Definition: qcaprovider.h:1791
QStringList issuerLocations
A list of URIs for issuer certificates.
Definition: qcaprovider.h:1183
QString addr
The IP address.
Definition: qcaprovider.h:2620
PKeyContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:917
Validity
The validity (or otherwise) of a certificate.
Definition: qca_cert.h:496
QByteArray issuerId
The issuer id.
Definition: qcaprovider.h:1309
DSAContext(Provider *p)
Standard constructor.
Definition: qcaprovider.h:765
BigInteger serial
The certificate serial number.
Definition: qcaprovider.h:1197
int number
The CRL number, which increases at each update.
Definition: qcaprovider.h:1279
QDateTime nextUpdate
The time this CRL expires, and the next CRL should be fetched.
Definition: qcaprovider.h:1289
QString cipherSuite
The cipher suite being used for this connection.
Definition: qcaprovider.h:2270
@ Error
Operation failed.
Definition: qcaprovider.h:2296
@ Verify
Verify operation.
Definition: qcaprovider.h:2924
@ Success
Operation completed.
Definition: qcaprovider.h:2633
SignMode
The type of message signature.
DLGroupSet
Well known discrete logarithm group sets.
CertBase(Provider *p, const QString &type)
Standard constructor.
Definition: qcaprovider.h:1071
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 03:50:02 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.