File indexing completed on 2024-04-28 04:43:42
0001 /* 0002 * qcaprovider.h - QCA Plugin API 0003 * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com> 0004 * Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net> 0005 * 0006 * This library is free software; you can redistribute it and/or 0007 * modify it under the terms of the GNU Lesser General Public 0008 * License as published by the Free Software Foundation; either 0009 * version 2.1 of the License, or (at your option) any later version. 0010 * 0011 * This library is distributed in the hope that it will be useful, 0012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0014 * Lesser General Public License for more details. 0015 * 0016 * You should have received a copy of the GNU Lesser General Public 0017 * License along with this library; if not, write to the Free Software 0018 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 0019 * 02110-1301 USA 0020 * 0021 */ 0022 0023 /** 0024 \file qcaprovider.h 0025 0026 Header file for provider implementation classes (plugins) 0027 0028 \note You should not use this header directly from an 0029 application. You should just use <tt> \#include \<QtCrypto> 0030 </tt> instead. 0031 */ 0032 0033 #ifndef QCAPROVIDER_H 0034 #define QCAPROVIDER_H 0035 0036 #include "qca_basic.h" 0037 #include "qca_cert.h" 0038 #include "qca_core.h" 0039 #include "qca_keystore.h" 0040 #include "qca_publickey.h" 0041 #include "qca_securelayer.h" 0042 #include "qca_securemessage.h" 0043 0044 #include <limits> 0045 0046 #ifndef DOXYGEN_NO_PROVIDER_API 0047 0048 /** 0049 \defgroup ProviderAPI QCA provider API 0050 0051 This group of classes is not normally needed 0052 by application writers, but can be used to extend QCA if 0053 required 0054 */ 0055 0056 /** 0057 \class QCAPlugin qcaprovider.h QtCrypto 0058 0059 Provider plugin base class 0060 0061 QCA loads cryptographic provider plugins with QPluginLoader. The QObject 0062 obtained when loading the plugin must implement the QCAPlugin interface. 0063 This is done by inheriting QCAPlugin, and including 0064 Q_INTERFACES(QCAPlugin) in your class declaration. 0065 0066 For example: 0067 \code 0068 class MyPlugin : public QObject, public QCAPlugin 0069 { 0070 Q_OBJECT 0071 Q_INTERFACES(QCAPlugin) 0072 public: 0073 virtual Provider *createProvider() { ... } 0074 }; 0075 \endcode 0076 0077 There is only one function to reimplement, called createProvider(). This 0078 function should return a newly allocated Provider instance. 0079 0080 \ingroup ProviderAPI 0081 */ 0082 class QCA_EXPORT QCAPlugin 0083 { 0084 public: 0085 /** 0086 Destructs the object 0087 */ 0088 virtual ~QCAPlugin() 0089 { 0090 } 0091 0092 /** 0093 Returns a newly allocated Provider instance. 0094 */ 0095 virtual QCA::Provider *createProvider() = 0; 0096 }; 0097 0098 Q_DECLARE_INTERFACE(QCAPlugin, "com.affinix.qca.Plugin/1.0") 0099 0100 namespace QCA { 0101 0102 /** 0103 \class InfoContext qcaprovider.h QtCrypto 0104 0105 Extended provider information 0106 0107 \note This class is part of the provider plugin interface and should not 0108 be used directly by applications. 0109 0110 \ingroup ProviderAPI 0111 */ 0112 class QCA_EXPORT InfoContext : public BasicContext 0113 { 0114 Q_OBJECT 0115 public: 0116 /** 0117 Standard constructor 0118 0119 \param p the provider associated with this context 0120 */ 0121 InfoContext(Provider *p) 0122 : BasicContext(p, QStringLiteral("info")) 0123 { 0124 } 0125 0126 /** 0127 The hash algorithms supported by the provider 0128 */ 0129 virtual QStringList supportedHashTypes() const; 0130 0131 /** 0132 The cipher algorithms supported by the provider 0133 */ 0134 virtual QStringList supportedCipherTypes() const; 0135 0136 /** 0137 The mac algorithms supported by the provider 0138 */ 0139 virtual QStringList supportedMACTypes() const; 0140 }; 0141 0142 /** 0143 \class RandomContext qcaprovider.h QtCrypto 0144 0145 Random provider 0146 0147 \note This class is part of the provider plugin interface and should not 0148 be used directly by applications. You probably want Random instead. 0149 0150 \ingroup ProviderAPI 0151 */ 0152 class QCA_EXPORT RandomContext : public BasicContext 0153 { 0154 Q_OBJECT 0155 public: 0156 /** 0157 Standard constructor 0158 0159 \param p the provider associated with this context 0160 */ 0161 RandomContext(Provider *p) 0162 : BasicContext(p, QStringLiteral("random")) 0163 { 0164 } 0165 0166 /** 0167 Return an array of random bytes 0168 0169 \param size the number of random bytes to return 0170 */ 0171 virtual SecureArray nextBytes(int size) = 0; 0172 }; 0173 0174 /** 0175 \class HashContext qcaprovider.h QtCrypto 0176 0177 Hash provider 0178 0179 \note This class is part of the provider plugin interface and should not 0180 be used directly by applications. You probably want Hash instead. 0181 0182 \ingroup ProviderAPI 0183 */ 0184 class QCA_EXPORT HashContext : public BasicContext 0185 { 0186 Q_OBJECT 0187 public: 0188 /** 0189 Standard constructor 0190 0191 \param p the provider associated with this context 0192 \param type the name of the type of hash provided by this context 0193 */ 0194 HashContext(Provider *p, const QString &type) 0195 : BasicContext(p, type) 0196 { 0197 } 0198 0199 /** 0200 Reset the object to its initial state 0201 */ 0202 virtual void clear() = 0; 0203 0204 /** 0205 Process a chunk of data 0206 0207 \param a the input data to process 0208 */ 0209 virtual void update(const MemoryRegion &a) = 0; 0210 0211 /** 0212 Return the computed hash 0213 */ 0214 virtual MemoryRegion final() = 0; 0215 }; 0216 0217 /** 0218 \class CipherContext qcaprovider.h QtCrypto 0219 0220 Cipher provider 0221 0222 \note This class is part of the provider plugin interface and should not 0223 be used directly by applications. You probably want Cipher instead. 0224 0225 \ingroup ProviderAPI 0226 */ 0227 class QCA_EXPORT CipherContext : public BasicContext 0228 { 0229 Q_OBJECT 0230 public: 0231 /** 0232 Standard constructor 0233 0234 \param p the provider associated with this context 0235 \param type the name of the type of cipher provided by this context 0236 0237 \note type includes the name of the cipher (e.g. "aes256"), the operating 0238 mode (e.g. "cbc" or "ofb") and the padding type (e.g. "pkcs7") if any. 0239 */ 0240 CipherContext(Provider *p, const QString &type) 0241 : BasicContext(p, type) 0242 { 0243 } 0244 0245 /** 0246 Set up the object for encrypt/decrypt 0247 0248 \param dir the direction for the cipher (encryption/decryption) 0249 \param key the symmetric key to use for the cipher 0250 \param iv the initialization vector to use for the cipher (not used in ECB mode) 0251 \param tag the AuthTag to use (only for GCM and CCM modes) 0252 */ 0253 virtual void setup(Direction dir, const SymmetricKey &key, const InitializationVector &iv, const AuthTag &tag) = 0; 0254 0255 /** 0256 Returns the KeyLength for this cipher 0257 */ 0258 virtual KeyLength keyLength() const = 0; 0259 0260 /** 0261 Returns the block size for this cipher 0262 */ 0263 virtual int blockSize() const = 0; 0264 0265 /** 0266 Returns the authentication tag for this cipher 0267 */ 0268 virtual AuthTag tag() const = 0; 0269 0270 /** 0271 Process a chunk of data. Returns true if successful. 0272 0273 \param in the input data to process 0274 \param out pointer to an array that should store the result 0275 */ 0276 virtual bool update(const SecureArray &in, SecureArray *out) = 0; 0277 0278 /** 0279 Finish the cipher processing. Returns true if successful. 0280 0281 \param out pointer to an array that should store the result 0282 */ 0283 virtual bool final(SecureArray *out) = 0; 0284 }; 0285 0286 /** 0287 \class MACContext qcaprovider.h QtCrypto 0288 0289 Message authentication code provider 0290 0291 \note This class is part of the provider plugin interface and should not 0292 be used directly by applications. You probably want 0293 MessageAuthenticationCode instead. 0294 0295 \ingroup ProviderAPI 0296 */ 0297 class QCA_EXPORT MACContext : public BasicContext 0298 { 0299 Q_OBJECT 0300 public: 0301 /** 0302 Standard constructor 0303 \param p the provider associated with this context 0304 \param type the name of the type of MAC algorithm provided by this context 0305 */ 0306 MACContext(Provider *p, const QString &type) 0307 : BasicContext(p, type) 0308 { 0309 } 0310 0311 /** 0312 Set up the object for hashing 0313 0314 \param key the key to use with the MAC. 0315 */ 0316 virtual void setup(const SymmetricKey &key) = 0; 0317 0318 /** 0319 Returns the KeyLength for this MAC algorithm 0320 */ 0321 virtual KeyLength keyLength() const = 0; 0322 0323 /** 0324 Process a chunk of data 0325 0326 \param in the input data to process 0327 */ 0328 virtual void update(const MemoryRegion &in) = 0; 0329 0330 /** 0331 Compute the result after processing all data 0332 0333 \param out pointer to an array that should store the result 0334 */ 0335 virtual void final(MemoryRegion *out) = 0; 0336 0337 protected: 0338 /** 0339 Returns a KeyLength that supports any length 0340 */ 0341 KeyLength anyKeyLength() const 0342 { 0343 // this is used instead of a default implementation to make sure that 0344 // provider authors think about it, at least a bit. 0345 // See Meyers, Effective C++, Effective C++ (2nd Ed), Item 36 0346 return KeyLength(0, INT_MAX, 1); 0347 } 0348 }; 0349 0350 /** 0351 \class KDFContext qcaprovider.h QtCrypto 0352 0353 Key derivation function provider 0354 0355 \note This class is part of the provider plugin interface and should not 0356 be used directly by applications. You probably want KeyDerivationFunction 0357 instead. 0358 0359 \ingroup ProviderAPI 0360 */ 0361 class QCA_EXPORT KDFContext : public BasicContext 0362 { 0363 Q_OBJECT 0364 public: 0365 /** 0366 Standard constructor 0367 0368 \param p the provider associated with this context 0369 \param type the name of the KDF provided by this context (including algorithm) 0370 */ 0371 KDFContext(Provider *p, const QString &type) 0372 : BasicContext(p, type) 0373 { 0374 } 0375 0376 /** 0377 Create a key and return it 0378 0379 \param secret the secret part (typically password) 0380 \param salt the salt / initialization vector 0381 \param keyLength the length of the key to be produced 0382 \param iterationCount the number of iterations of the derivation algorithm 0383 */ 0384 virtual SymmetricKey makeKey(const SecureArray &secret, 0385 const InitializationVector &salt, 0386 unsigned int keyLength, 0387 unsigned int iterationCount) = 0; 0388 0389 /** 0390 Create a key and return it 0391 0392 \param secret the secret part (typically password) 0393 \param salt the salt / initialization vector 0394 \param keyLength the length of the key to be produced 0395 \param msecInterval the maximum time to compute the key, in milliseconds 0396 \param iterationCount a pointer to store the number of iterations of the derivation algorithm 0397 */ 0398 virtual SymmetricKey makeKey(const SecureArray &secret, 0399 const InitializationVector &salt, 0400 unsigned int keyLength, 0401 int msecInterval, 0402 unsigned int *iterationCount) = 0; 0403 }; 0404 0405 /** 0406 \class HKDFContext qcaprovider.h QtCrypto 0407 0408 HKDF provider 0409 0410 \note This class is part of the provider plugin interface and should not 0411 be used directly by applications. You probably want HKDF instead. 0412 0413 \ingroup ProviderAPI 0414 */ 0415 class QCA_EXPORT HKDFContext : public BasicContext 0416 { 0417 Q_OBJECT 0418 public: 0419 /** 0420 Standard constructor 0421 0422 \param p the provider associated with this context 0423 \param type the name of the HKDF provided by this context (including algorithm) 0424 */ 0425 HKDFContext(Provider *p, const QString &type) 0426 : BasicContext(p, type) 0427 { 0428 } 0429 0430 /** 0431 Create a key and return it 0432 0433 \param secret the secret part (typically password) 0434 \param salt the salt / initialization vector 0435 \param info the info / initialization vector 0436 \param keyLength the length of the key to be produced 0437 */ 0438 virtual SymmetricKey makeKey(const SecureArray &secret, 0439 const InitializationVector &salt, 0440 const InitializationVector &info, 0441 unsigned int keyLength) = 0; 0442 }; 0443 0444 /** 0445 \class DLGroupContext qcaprovider.h QtCrypto 0446 0447 Discrete logarithm provider 0448 0449 \note This class is part of the provider plugin interface and should not 0450 be used directly by applications. You probably want DLGroup instead. 0451 0452 \ingroup ProviderAPI 0453 */ 0454 class QCA_EXPORT DLGroupContext : public Provider::Context 0455 { 0456 Q_OBJECT 0457 public: 0458 /** 0459 Standard constructor 0460 0461 \param p the provider associated with this context 0462 */ 0463 DLGroupContext(Provider *p) 0464 : Provider::Context(p, QStringLiteral("dlgroup")) 0465 { 0466 } 0467 0468 /** 0469 The DLGroupSets supported by this object 0470 */ 0471 virtual QList<DLGroupSet> supportedGroupSets() const = 0; 0472 0473 /** 0474 Returns true if there is a result to obtain 0475 */ 0476 virtual bool isNull() const = 0; 0477 0478 /** 0479 Attempt to create P, Q, and G values from the specified group set 0480 0481 If \a block is true, then this function blocks until completion. 0482 Otherwise, this function returns immediately and finished() is 0483 emitted when the operation completes. 0484 0485 If an error occurs during generation, then the operation will 0486 complete and isNull() will return true. 0487 0488 \param set the group set to generate the key from 0489 \param block whether to block (true) or not (false) 0490 */ 0491 virtual void fetchGroup(DLGroupSet set, bool block) = 0; 0492 0493 /** 0494 Obtain the result of the operation. Ensure isNull() returns false 0495 before calling this function. 0496 0497 \param p the P value 0498 \param q the Q value 0499 \param g the G value 0500 */ 0501 virtual void getResult(BigInteger *p, BigInteger *q, BigInteger *g) const = 0; 0502 0503 Q_SIGNALS: 0504 /** 0505 Emitted when the fetchGroup() operation completes in non-blocking 0506 mode. 0507 */ 0508 void finished(); 0509 }; 0510 0511 /** 0512 \class PKeyBase qcaprovider.h QtCrypto 0513 0514 Public key implementation provider base 0515 0516 \note This class is part of the provider plugin interface and should not 0517 be used directly by applications. You probably want PKey, PublicKey, or 0518 PrivateKey instead. 0519 0520 \ingroup ProviderAPI 0521 */ 0522 class QCA_EXPORT PKeyBase : public BasicContext 0523 { 0524 Q_OBJECT 0525 public: 0526 /** 0527 Standard constructor 0528 0529 \param p the Provider associated with this context 0530 \param type type of key provided by this context 0531 */ 0532 PKeyBase(Provider *p, const QString &type); 0533 0534 /** 0535 Returns true if this object is not valid. This is the default 0536 state, and the object may also become this state if a conversion 0537 or generation function fails. 0538 */ 0539 virtual bool isNull() const = 0; 0540 0541 /** 0542 Returns the type of public key 0543 */ 0544 virtual PKey::Type type() const = 0; 0545 0546 /** 0547 Returns true if this is a private key, otherwise false 0548 */ 0549 virtual bool isPrivate() const = 0; 0550 0551 /** 0552 Returns true if the components of this key are accessible and 0553 whether it can be serialized into an output format. Private keys 0554 from a smart card device will often not be exportable. 0555 */ 0556 virtual bool canExport() const = 0; 0557 0558 /** 0559 If the key is a private key, this function will convert it into a 0560 public key (all private key data includes the public data as well, 0561 which is why this is possible). If the key is already a public 0562 key, then this function has no effect. 0563 */ 0564 virtual void convertToPublic() = 0; 0565 0566 /** 0567 Returns the number of bits in the key 0568 */ 0569 virtual int bits() const = 0; 0570 0571 /** 0572 Returns the maximum number of bytes that can be encrypted by this 0573 key 0574 0575 \param alg the algorithm to be used for encryption 0576 */ 0577 virtual int maximumEncryptSize(EncryptionAlgorithm alg) const; 0578 0579 /** 0580 Encrypt data 0581 0582 \param in the input data to encrypt 0583 \param alg the encryption algorithm to use 0584 */ 0585 virtual SecureArray encrypt(const SecureArray &in, EncryptionAlgorithm alg); 0586 0587 /** 0588 Decrypt data 0589 0590 \param in the input data to decrypt 0591 \param out pointer to an array to store the plaintext result 0592 \param alg the encryption algorithm used to generate the input 0593 data 0594 */ 0595 virtual bool decrypt(const SecureArray &in, SecureArray *out, EncryptionAlgorithm alg); 0596 0597 /** 0598 Begin a signing operation 0599 0600 \param alg the signature algorithm to use 0601 \param format the signature format to use 0602 */ 0603 virtual void startSign(SignatureAlgorithm alg, SignatureFormat format); 0604 0605 /** 0606 Begin a verify operation 0607 0608 \param alg the signature algorithm used by the input signature 0609 \param format the signature format used by the input signature 0610 */ 0611 virtual void startVerify(SignatureAlgorithm alg, SignatureFormat format); 0612 0613 /** 0614 Process the plaintext input data for either signing or verifying, 0615 whichever operation is active. 0616 0617 \param in the input data to process 0618 */ 0619 virtual void update(const MemoryRegion &in); 0620 0621 /** 0622 Complete a signing operation, and return the signature value 0623 0624 If there is an error signing, an empty array is returned. 0625 */ 0626 virtual QByteArray endSign(); 0627 0628 /** 0629 Complete a verify operation, and return true if successful 0630 0631 If there is an error verifying, this function returns false. 0632 0633 \param sig the signature to verify with the input data 0634 */ 0635 virtual bool endVerify(const QByteArray &sig); 0636 0637 /** 0638 Compute a symmetric key based on this private key and some other 0639 public key 0640 0641 Essentially for Diffie-Hellman only. 0642 0643 \param theirs the other side (public key) to be used for key generation. 0644 */ 0645 virtual SymmetricKey deriveKey(const PKeyBase &theirs); 0646 0647 Q_SIGNALS: 0648 /** 0649 Emitted when an asynchronous operation completes on this key. 0650 Such operations will be documented that they emit this signal. 0651 */ 0652 void finished(); 0653 }; 0654 0655 /** 0656 \class RSAContext qcaprovider.h QtCrypto 0657 0658 RSA provider 0659 0660 \note This class is part of the provider plugin interface and should not 0661 be used directly by applications. You probably want RSAPublicKey or 0662 RSAPrivateKey instead. 0663 0664 \ingroup ProviderAPI 0665 */ 0666 class QCA_EXPORT RSAContext : public PKeyBase 0667 { 0668 Q_OBJECT 0669 public: 0670 /** 0671 Standard constructor 0672 0673 \param p the provider associated with this context 0674 */ 0675 RSAContext(Provider *p) 0676 : PKeyBase(p, QStringLiteral("rsa")) 0677 { 0678 } 0679 0680 /** 0681 Generate an RSA private key 0682 0683 If \a block is true, then this function blocks until completion. 0684 Otherwise, this function returns immediately and finished() is 0685 emitted when the operation completes. 0686 0687 If an error occurs during generation, then the operation will 0688 complete and isNull() will return true. 0689 0690 \param bits the length of the key to generate, in bits 0691 \param exp the exponent to use for generation 0692 \param block whether to use blocking mode 0693 */ 0694 virtual void createPrivate(int bits, int exp, bool block) = 0; 0695 0696 /** 0697 Create an RSA private key based on the five components 0698 0699 \param n the N parameter 0700 \param e the public exponent 0701 \param p the P parameter 0702 \param q the Q parameter 0703 \param d the D parameter 0704 */ 0705 virtual void createPrivate(const BigInteger &n, 0706 const BigInteger &e, 0707 const BigInteger &p, 0708 const BigInteger &q, 0709 const BigInteger &d) = 0; 0710 0711 /** 0712 Create an RSA public key based on the two public components 0713 0714 \param n the N parameter 0715 \param e the public exponent 0716 */ 0717 virtual void createPublic(const BigInteger &n, const BigInteger &e) = 0; 0718 0719 /** 0720 Returns the public N component of this RSA key 0721 */ 0722 virtual BigInteger n() const = 0; 0723 0724 /** 0725 Returns the public E component of this RSA key 0726 */ 0727 virtual BigInteger e() const = 0; 0728 0729 /** 0730 Returns the private P component of this RSA key 0731 */ 0732 virtual BigInteger p() const = 0; 0733 0734 /** 0735 Returns the private Q component of this RSA key 0736 */ 0737 virtual BigInteger q() const = 0; 0738 0739 /** 0740 Returns the private D component of this RSA key 0741 */ 0742 virtual BigInteger d() const = 0; 0743 }; 0744 0745 /** 0746 \class DSAContext qcaprovider.h QtCrypto 0747 0748 DSA provider 0749 0750 \note This class is part of the provider plugin interface and should not 0751 be used directly by applications. You probably want DSAPublicKey or 0752 DSAPrivateKey instead. 0753 0754 \ingroup ProviderAPI 0755 */ 0756 class QCA_EXPORT DSAContext : public PKeyBase 0757 { 0758 Q_OBJECT 0759 public: 0760 /** 0761 Standard constructor 0762 0763 \param p the provider associated with this context 0764 */ 0765 DSAContext(Provider *p) 0766 : PKeyBase(p, QStringLiteral("dsa")) 0767 { 0768 } 0769 0770 /** 0771 Generate a DSA private key 0772 0773 If \a block is true, then this function blocks until completion. 0774 Otherwise, this function returns immediately and finished() is 0775 emitted when the operation completes. 0776 0777 If an error occurs during generation, then the operation will 0778 complete and isNull() will return true. 0779 0780 \param domain the domain values to use for generation 0781 \param block whether to use blocking mode 0782 */ 0783 virtual void createPrivate(const DLGroup &domain, bool block) = 0; 0784 0785 /** 0786 Create a DSA private key based on its numeric components 0787 0788 \param domain the domain values to use for generation 0789 \param y the public Y component 0790 \param x the private X component 0791 */ 0792 virtual void createPrivate(const DLGroup &domain, const BigInteger &y, const BigInteger &x) = 0; 0793 0794 /** 0795 Create a DSA public key based on its numeric components 0796 0797 \param domain the domain values to use for generation 0798 \param y the public Y component 0799 */ 0800 virtual void createPublic(const DLGroup &domain, const BigInteger &y) = 0; 0801 0802 /** 0803 Returns the public domain component of this DSA key 0804 */ 0805 virtual DLGroup domain() const = 0; 0806 0807 /** 0808 Returns the public Y component of this DSA key 0809 */ 0810 virtual BigInteger y() const = 0; 0811 0812 /** 0813 Returns the private X component of this DSA key 0814 */ 0815 virtual BigInteger x() const = 0; 0816 }; 0817 0818 /** 0819 \class DHContext qcaprovider.h QtCrypto 0820 0821 Diffie-Hellman provider 0822 0823 \note This class is part of the provider plugin interface and should not 0824 be used directly by applications. You probably want DHPublicKey or 0825 DHPrivateKey instead. 0826 0827 \ingroup ProviderAPI 0828 */ 0829 class QCA_EXPORT DHContext : public PKeyBase 0830 { 0831 Q_OBJECT 0832 public: 0833 /** 0834 Standard constructor 0835 0836 \param p the provider associated with this context 0837 */ 0838 DHContext(Provider *p) 0839 : PKeyBase(p, QStringLiteral("dh")) 0840 { 0841 } 0842 0843 /** 0844 Generate a Diffie-Hellman private key 0845 0846 If \a block is true, then this function blocks until completion. 0847 Otherwise, this function returns immediately and finished() is 0848 emitted when the operation completes. 0849 0850 If an error occurs during generation, then the operation will 0851 complete and isNull() will return true. 0852 0853 \param domain the domain values to use for generation 0854 \param block whether to use blocking mode 0855 */ 0856 virtual void createPrivate(const DLGroup &domain, bool block) = 0; 0857 0858 /** 0859 Create a Diffie-Hellman private key based on its numeric 0860 components 0861 0862 \param domain the domain values to use for generation 0863 \param y the public Y component 0864 \param x the private X component 0865 */ 0866 virtual void createPrivate(const DLGroup &domain, const BigInteger &y, const BigInteger &x) = 0; 0867 0868 /** 0869 Create a Diffie-Hellman public key based on its numeric 0870 components 0871 0872 \param domain the domain values to use for generation 0873 \param y the public Y component 0874 */ 0875 virtual void createPublic(const DLGroup &domain, const BigInteger &y) = 0; 0876 0877 /** 0878 Returns the public domain component of this Diffie-Hellman key 0879 */ 0880 virtual DLGroup domain() const = 0; 0881 0882 /** 0883 Returns the public Y component of this Diffie-Hellman key 0884 */ 0885 virtual BigInteger y() const = 0; 0886 0887 /** 0888 Returns the private X component of this Diffie-Hellman key 0889 */ 0890 virtual BigInteger x() const = 0; 0891 }; 0892 0893 /** 0894 \class PKeyContext qcaprovider.h QtCrypto 0895 0896 Public key container provider 0897 0898 \note This class is part of the provider plugin interface and should not 0899 be used directly by applications. You probably want PKey, PublicKey, or 0900 PrivateKey instead. 0901 0902 This object "holds" a public key object. By default it contains no key 0903 (key() returns 0), but you can put a key into it with setKey(), or you 0904 can call an import function such as publicFromDER(). 0905 0906 \ingroup ProviderAPI 0907 */ 0908 class QCA_EXPORT PKeyContext : public BasicContext 0909 { 0910 Q_OBJECT 0911 public: 0912 /** 0913 Standard constructor 0914 0915 \param p the provider associated with this context 0916 */ 0917 PKeyContext(Provider *p) 0918 : BasicContext(p, QStringLiteral("pkey")) 0919 { 0920 } 0921 0922 /** 0923 Returns a list of supported public key types 0924 */ 0925 virtual QList<PKey::Type> supportedTypes() const = 0; 0926 0927 /** 0928 Returns a list of public key types that can be serialized and 0929 deserialized into DER and PEM format 0930 */ 0931 virtual QList<PKey::Type> supportedIOTypes() const = 0; 0932 0933 /** 0934 Returns a list of password-based encryption algorithms that are 0935 supported for private key serialization and deserialization 0936 */ 0937 virtual QList<PBEAlgorithm> supportedPBEAlgorithms() const = 0; 0938 0939 /** 0940 Returns the key held by this object, or 0 if there is no key 0941 */ 0942 virtual PKeyBase *key() = 0; 0943 0944 /** 0945 Returns the key held by this object, or 0 if there is no key 0946 */ 0947 virtual const PKeyBase *key() const = 0; 0948 0949 /** 0950 Sets the key for this object. If this object already had a key, 0951 then the old one is destructed. This object takes ownership of 0952 the key. 0953 0954 \param key the key to be set for this object 0955 */ 0956 virtual void setKey(PKeyBase *key) = 0; 0957 0958 /** 0959 Attempt to import a key from another provider. Returns true if 0960 successful, otherwise false. 0961 0962 Generally this function is used if the specified key's provider 0963 does not support serialization, but your provider does. The call 0964 to this function would then be followed by an export function, 0965 such as publicToDER(). 0966 0967 \param key the key to be imported 0968 */ 0969 virtual bool importKey(const PKeyBase *key) = 0; 0970 0971 /** 0972 Convert a public key to DER format, and return the value 0973 0974 Returns an empty array on error. 0975 */ 0976 virtual QByteArray publicToDER() const; 0977 0978 /** 0979 Convert a public key to PEM format, and return the value 0980 0981 Returns an empty string on error. 0982 */ 0983 virtual QString publicToPEM() const; 0984 0985 /** 0986 Read DER-formatted input and convert it into a public key 0987 0988 Returns QCA::ConvertGood if successful, otherwise some error 0989 value. 0990 0991 \param a the input data 0992 */ 0993 virtual ConvertResult publicFromDER(const QByteArray &a); 0994 0995 /** 0996 Read PEM-formatted input and convert it into a public key 0997 0998 Returns QCA::ConvertGood if successful, otherwise some error 0999 value. 1000 1001 \param s the input data 1002 */ 1003 virtual ConvertResult publicFromPEM(const QString &s); 1004 1005 /** 1006 Convert a private key to DER format, and return the value 1007 1008 Returns an empty array on error. 1009 1010 \param passphrase the passphrase to encode the result with, or an 1011 empty array if no encryption is desired 1012 \param pbe the encryption algorithm to use, if applicable 1013 */ 1014 virtual SecureArray privateToDER(const SecureArray &passphrase, PBEAlgorithm pbe) const; 1015 1016 /** 1017 Convert a private key to PEM format, and return the value 1018 1019 Returns an empty string on error. 1020 1021 \param passphrase the passphrase to encode the result with, or an 1022 empty array if no encryption is desired 1023 \param pbe the encryption algorithm to use, if applicable 1024 */ 1025 virtual QString privateToPEM(const SecureArray &passphrase, PBEAlgorithm pbe) const; 1026 1027 /** 1028 Read DER-formatted input and convert it into a private key 1029 1030 Returns QCA::ConvertGood if successful, otherwise some error 1031 value. 1032 1033 \param a the input data 1034 \param passphrase the passphrase needed to decrypt, if applicable 1035 */ 1036 virtual ConvertResult privateFromDER(const SecureArray &a, const SecureArray &passphrase); 1037 1038 /** 1039 Read PEM-formatted input and convert it into a private key 1040 1041 Returns QCA::ConvertGood if successful, otherwise some error 1042 value. 1043 1044 \param s the input data 1045 \param passphrase the passphrase needed to decrypt, if applicable 1046 */ 1047 virtual ConvertResult privateFromPEM(const QString &s, const SecureArray &passphrase); 1048 }; 1049 1050 /** 1051 \class CertBase qcaprovider.h QtCrypto 1052 1053 X.509 certificate and certificate request provider base 1054 1055 \note This class is part of the provider plugin interface and should not 1056 be used directly by applications. You probably want Certificate, 1057 CertificateRequest, or CRL instead. 1058 1059 \ingroup ProviderAPI 1060 */ 1061 class QCA_EXPORT CertBase : public BasicContext 1062 { 1063 Q_OBJECT 1064 public: 1065 /** 1066 Standard constructor 1067 1068 \param p the provider associated with this context 1069 \param type the type of certificate-like object provided by this context 1070 */ 1071 CertBase(Provider *p, const QString &type) 1072 : BasicContext(p, type) 1073 { 1074 } 1075 1076 /** 1077 Convert this object to DER format, and return the value 1078 1079 Returns an empty array on error. 1080 */ 1081 virtual QByteArray toDER() const = 0; 1082 1083 /** 1084 Convert this object to PEM format, and return the value 1085 1086 Returns an empty string on error. 1087 */ 1088 virtual QString toPEM() const = 0; 1089 1090 /** 1091 Read DER-formatted input and convert it into this object 1092 1093 Returns QCA::ConvertGood if successful, otherwise some error 1094 value. 1095 1096 \param a the input data 1097 */ 1098 virtual ConvertResult fromDER(const QByteArray &a) = 0; 1099 1100 /** 1101 Read PEM-formatted input and convert it into this object 1102 1103 Returns QCA::ConvertGood if successful, otherwise some error 1104 value. 1105 1106 \param s the input data 1107 */ 1108 virtual ConvertResult fromPEM(const QString &s) = 0; 1109 }; 1110 1111 /** 1112 \class CertContextProps qcaprovider.h QtCrypto 1113 1114 X.509 certificate or certificate request properties 1115 1116 \note This class is part of the provider plugin interface and should not 1117 be used directly by applications. You probably want Certificate or 1118 CertificateRequest instead. 1119 1120 Some fields are only for certificates or only for certificate requests, 1121 and these fields are noted. 1122 1123 \ingroup ProviderAPI 1124 */ 1125 class QCA_EXPORT CertContextProps 1126 { 1127 public: 1128 /** 1129 The X.509 certificate version, usually 3 1130 1131 This field is for certificates only. 1132 */ 1133 int version; 1134 1135 /** 1136 The time the certificate becomes valid (often the time of create) 1137 1138 This field is for certificates only. 1139 */ 1140 QDateTime start; 1141 1142 /** 1143 The time the certificate expires 1144 1145 This field is for certificates only. 1146 */ 1147 QDateTime end; 1148 1149 /** 1150 The subject information 1151 */ 1152 CertificateInfoOrdered subject; 1153 1154 /** 1155 The issuer information 1156 1157 This field is for certificates only. 1158 */ 1159 CertificateInfoOrdered issuer; 1160 1161 /** 1162 The constraints 1163 */ 1164 Constraints constraints; 1165 1166 /** 1167 The policies 1168 */ 1169 QStringList policies; 1170 1171 /** 1172 A list of URIs for CRLs 1173 1174 This field is for certificates only. 1175 */ 1176 QStringList crlLocations; 1177 1178 /** 1179 A list of URIs for issuer certificates 1180 1181 This field is for certificates only. 1182 */ 1183 QStringList issuerLocations; 1184 1185 /** 1186 A list of URIs for OCSP services 1187 1188 This field is for certificates only. 1189 */ 1190 QStringList ocspLocations; 1191 1192 /** 1193 The certificate serial number 1194 1195 This field is for certificates only. 1196 */ 1197 BigInteger serial; 1198 1199 /** 1200 True if the certificate is a CA or the certificate request is 1201 requesting to be a CA, otherwise false 1202 */ 1203 bool isCA; 1204 1205 /** 1206 True if the certificate is self-signed 1207 1208 This field is for certificates only. 1209 */ 1210 bool isSelfSigned; 1211 1212 /** 1213 The path limit 1214 */ 1215 int pathLimit; 1216 1217 /** 1218 The signature data 1219 */ 1220 QByteArray sig; 1221 1222 /** 1223 The signature algorithm used to create the signature 1224 */ 1225 SignatureAlgorithm sigalgo; 1226 1227 /** 1228 The subject id 1229 1230 This field is for certificates only. 1231 */ 1232 QByteArray subjectId; 1233 1234 /** 1235 The issuer id 1236 1237 This field is for certificates only. 1238 */ 1239 QByteArray issuerId; 1240 1241 /** 1242 The SPKAC challenge value 1243 1244 This field is for certificate requests only. 1245 */ 1246 QString challenge; 1247 1248 /** 1249 The format used for the certificate request 1250 1251 This field is for certificate requests only. 1252 */ 1253 CertificateRequestFormat format; 1254 }; 1255 1256 /** 1257 \class CRLContextProps qcaprovider.h QtCrypto 1258 1259 X.509 certificate revocation list properties 1260 1261 \note This class is part of the provider plugin interface and should not 1262 be used directly by applications. You probably want CRL instead. 1263 1264 For efficiency and simplicity, the members are directly accessed. 1265 1266 \ingroup ProviderAPI 1267 */ 1268 class QCA_EXPORT CRLContextProps 1269 { 1270 public: 1271 /** 1272 The issuer information of the CRL 1273 */ 1274 CertificateInfoOrdered issuer; 1275 1276 /** 1277 The CRL number, which increases at each update 1278 */ 1279 int number; 1280 1281 /** 1282 The time this CRL was created 1283 */ 1284 QDateTime thisUpdate; 1285 1286 /** 1287 The time this CRL expires, and the next CRL should be fetched 1288 */ 1289 QDateTime nextUpdate; 1290 1291 /** 1292 The revoked entries 1293 */ 1294 QList<CRLEntry> revoked; 1295 1296 /** 1297 The signature data of the CRL 1298 */ 1299 QByteArray sig; 1300 1301 /** 1302 The signature algorithm used by the issuer to sign the CRL 1303 */ 1304 SignatureAlgorithm sigalgo; 1305 1306 /** 1307 The issuer id 1308 */ 1309 QByteArray issuerId; 1310 }; 1311 1312 class CRLContext; 1313 1314 /** 1315 \class CertContext qcaprovider.h QtCrypto 1316 1317 X.509 certificate provider 1318 1319 \note This class is part of the provider plugin interface and should not 1320 be used directly by applications. You probably want Certificate instead. 1321 1322 \ingroup ProviderAPI 1323 */ 1324 class QCA_EXPORT CertContext : public CertBase 1325 { 1326 Q_OBJECT 1327 public: 1328 /** 1329 Standard constructor 1330 1331 \param p the provider associated with this context 1332 */ 1333 CertContext(Provider *p) 1334 : CertBase(p, QStringLiteral("cert")) 1335 { 1336 } 1337 1338 /** 1339 Create a self-signed certificate based on the given options and 1340 private key. Returns true if successful, otherwise false. 1341 1342 If successful, this object becomes the self-signed certificate. 1343 If unsuccessful, this object is considered to be in an 1344 uninitialized state. 1345 1346 \param opts the options to set on the certificate 1347 \param priv the key to be used to sign the certificate 1348 */ 1349 virtual bool createSelfSigned(const CertificateOptions &opts, const PKeyContext &priv) = 0; 1350 1351 /** 1352 Returns a pointer to the properties of this certificate 1353 */ 1354 virtual const CertContextProps *props() const = 0; 1355 1356 /** 1357 Returns true if this certificate is equal to another certificate, 1358 otherwise false 1359 1360 \param other the certificate to compare with 1361 */ 1362 virtual bool compare(const CertContext *other) const = 0; 1363 1364 /** 1365 Returns a copy of this certificate's public key. The caller is 1366 responsible for deleting it. 1367 */ 1368 virtual PKeyContext *subjectPublicKey() const = 0; 1369 1370 /** 1371 Returns true if this certificate is an issuer of another 1372 certificate, otherwise false 1373 1374 \param other the issued certificate to check 1375 */ 1376 virtual bool isIssuerOf(const CertContext *other) const = 0; 1377 1378 /** 1379 Validate this certificate 1380 1381 This function is blocking. 1382 1383 \param trusted list of trusted certificates 1384 \param untrusted list of untrusted certificates (can be empty) 1385 \param crls list of CRLs (can be empty) 1386 \param u the desired usage for this certificate 1387 \param vf validation options 1388 */ 1389 virtual Validity validate(const QList<CertContext *> &trusted, 1390 const QList<CertContext *> &untrusted, 1391 const QList<CRLContext *> &crls, 1392 UsageMode u, 1393 ValidateFlags vf) const = 0; 1394 1395 /** 1396 Validate a certificate chain. This function makes no use of the 1397 certificate represented by this object, and it can be used even 1398 if this object is in an uninitialized state. 1399 1400 This function is blocking. 1401 1402 \param chain list of certificates in the chain, starting with the 1403 user certificate. It is not necessary for the chain to contain 1404 the final root certificate. 1405 \param trusted list of trusted certificates 1406 \param crls list of CRLs (can be empty) 1407 \param u the desired usage for the user certificate in the chain 1408 \param vf validation options 1409 */ 1410 virtual Validity validate_chain(const QList<CertContext *> &chain, 1411 const QList<CertContext *> &trusted, 1412 const QList<CRLContext *> &crls, 1413 UsageMode u, 1414 ValidateFlags vf) const = 0; 1415 }; 1416 1417 /** 1418 \class CSRContext qcaprovider.h QtCrypto 1419 1420 X.509 certificate request provider 1421 1422 \note This class is part of the provider plugin interface and should not 1423 be used directly by applications. You probably want CertificateRequest 1424 instead. 1425 1426 \ingroup ProviderAPI 1427 */ 1428 class QCA_EXPORT CSRContext : public CertBase 1429 { 1430 Q_OBJECT 1431 public: 1432 /** 1433 Standard constructor 1434 1435 \param p the provider associated with this context 1436 */ 1437 CSRContext(Provider *p) 1438 : CertBase(p, QStringLiteral("csr")) 1439 { 1440 } 1441 1442 /** 1443 Returns true if the provider of this object supports the specified 1444 format, otherwise false 1445 1446 \param f the format to test for support for. 1447 */ 1448 virtual bool canUseFormat(CertificateRequestFormat f) const = 0; 1449 1450 /** 1451 Create a certificate request based on the given options and 1452 private key. Returns true if successful, otherwise false. 1453 1454 If successful, this object becomes the certificate request. 1455 If unsuccessful, this object is considered to be in an 1456 uninitialized state. 1457 1458 \param opts the options to set on the certificate 1459 \param priv the key to be used to sign the certificate 1460 */ 1461 virtual bool createRequest(const CertificateOptions &opts, const PKeyContext &priv) = 0; 1462 1463 /** 1464 Returns a pointer to the properties of this certificate request 1465 */ 1466 virtual const CertContextProps *props() const = 0; 1467 1468 /** 1469 Returns true if this certificate request is equal to another 1470 certificate request, otherwise false 1471 1472 \param other the certificate request to compare with 1473 */ 1474 virtual bool compare(const CSRContext *other) const = 0; 1475 1476 /** 1477 Returns a copy of this certificate request's public key. The 1478 caller is responsible for deleting it. 1479 */ 1480 virtual PKeyContext *subjectPublicKey() const = 0; 1481 1482 /** 1483 Convert this certificate request to Netscape SPKAC format, and 1484 return the value 1485 1486 Returns an empty string on error. 1487 */ 1488 virtual QString toSPKAC() const = 0; 1489 1490 /** 1491 Read Netscape SPKAC input and convert it into a certificate 1492 request 1493 1494 Returns QCA::ConvertGood if successful, otherwise some error 1495 value. 1496 1497 \param s the input data 1498 */ 1499 virtual ConvertResult fromSPKAC(const QString &s) = 0; 1500 }; 1501 1502 /** 1503 \class CRLContext qcaprovider.h QtCrypto 1504 1505 X.509 certificate revocation list provider 1506 1507 \note This class is part of the provider plugin interface and should not 1508 be used directly by applications. You probably want CRL instead. 1509 1510 \ingroup ProviderAPI 1511 */ 1512 class QCA_EXPORT CRLContext : public CertBase 1513 { 1514 Q_OBJECT 1515 public: 1516 /** 1517 Standard constructor 1518 1519 \param p the provider associated with this context 1520 */ 1521 CRLContext(Provider *p) 1522 : CertBase(p, QStringLiteral("crl")) 1523 { 1524 } 1525 1526 /** 1527 Returns a pointer to the properties of this CRL 1528 */ 1529 virtual const CRLContextProps *props() const = 0; 1530 1531 /** 1532 Returns true if this CRL is equal to another CRL, otherwise false 1533 1534 \param other the CRL to compare with 1535 */ 1536 virtual bool compare(const CRLContext *other) const = 0; 1537 }; 1538 1539 /** 1540 \class CertCollectionContext qcaprovider.h QtCrypto 1541 1542 X.509 certificate collection provider 1543 1544 \note This class is part of the provider plugin interface and should not 1545 be used directly by applications. You probably want CertificateCollection 1546 instead. 1547 1548 \ingroup ProviderAPI 1549 */ 1550 class QCA_EXPORT CertCollectionContext : public BasicContext 1551 { 1552 Q_OBJECT 1553 public: 1554 /** 1555 Standard constructor 1556 1557 \param p the provider associated with this context 1558 */ 1559 CertCollectionContext(Provider *p) 1560 : BasicContext(p, QStringLiteral("certcollection")) 1561 { 1562 } 1563 1564 /** 1565 Create PKCS#7 DER output based on the input certificates and CRLs 1566 1567 Returns an empty array on error. 1568 1569 \param certs list of certificates to store in the output 1570 \param crls list of CRLs to store in the output 1571 */ 1572 virtual QByteArray toPKCS7(const QList<CertContext *> &certs, const QList<CRLContext *> &crls) const = 0; 1573 1574 /** 1575 Read PKCS#7 DER input and convert it into a list of certificates 1576 and CRLs 1577 1578 The caller is responsible for deleting the returned items. 1579 1580 Returns QCA::ConvertGood if successful, otherwise some error 1581 value. 1582 1583 \param a the input data 1584 \param certs the destination list for the certificates 1585 \param crls the destination list for the CRLs 1586 */ 1587 virtual ConvertResult 1588 fromPKCS7(const QByteArray &a, QList<CertContext *> *certs, QList<CRLContext *> *crls) const = 0; 1589 }; 1590 1591 /** 1592 \class CAContext qcaprovider.h QtCrypto 1593 1594 X.509 certificate authority provider 1595 1596 \note This class is part of the provider plugin interface and should not 1597 be used directly by applications. You probably want CertificateAuthority 1598 instead. 1599 1600 \ingroup ProviderAPI 1601 */ 1602 class QCA_EXPORT CAContext : public BasicContext 1603 { 1604 Q_OBJECT 1605 public: 1606 /** 1607 Standard constructor 1608 1609 \param p the Provider associated with this context 1610 */ 1611 CAContext(Provider *p) 1612 : BasicContext(p, QStringLiteral("ca")) 1613 { 1614 } 1615 1616 /** 1617 Prepare the object for usage 1618 1619 This must be called before any CA operations are performed. 1620 1621 \param cert the certificate of the CA 1622 \param priv the private key of the CA 1623 */ 1624 virtual void setup(const CertContext &cert, const PKeyContext &priv) = 0; 1625 1626 /** 1627 Returns a copy of the CA's certificate. The caller is responsible 1628 for deleting it. 1629 */ 1630 virtual CertContext *certificate() const = 0; 1631 1632 /** 1633 Issue a certificate based on a certificate request, and return 1634 the certificate. The caller is responsible for deleting it. 1635 1636 \param req the certificate request 1637 \param notValidAfter the expiration date 1638 */ 1639 virtual CertContext *signRequest(const CSRContext &req, const QDateTime ¬ValidAfter) const = 0; 1640 1641 /** 1642 Issue a certificate based on a public key and options, and return 1643 the certificate. The caller is responsible for deleting it. 1644 1645 \param pub the public key of the certificate 1646 \param opts the options to use for generation 1647 */ 1648 virtual CertContext *createCertificate(const PKeyContext &pub, const CertificateOptions &opts) const = 0; 1649 1650 /** 1651 Create a new CRL and return it. The caller is responsible for 1652 deleting it. 1653 1654 The CRL has no entries in it. 1655 1656 \param nextUpdate the expiration date of the CRL 1657 */ 1658 virtual CRLContext *createCRL(const QDateTime &nextUpdate) const = 0; 1659 1660 /** 1661 Update an existing CRL, by examining an old one and creating a new 1662 one based on it. The new CRL is returned, and the caller is 1663 responsible for deleting it. 1664 1665 \param crl an existing CRL issued by this CA 1666 \param entries the list of revoked entries 1667 \param nextUpdate the expiration date of the new CRL 1668 */ 1669 virtual CRLContext * 1670 updateCRL(const CRLContext &crl, const QList<CRLEntry> &entries, const QDateTime &nextUpdate) const = 0; 1671 }; 1672 1673 /** 1674 \class PKCS12Context qcaprovider.h QtCrypto 1675 1676 PKCS#12 provider 1677 1678 \note This class is part of the provider plugin interface and should not 1679 be used directly by applications. You probably want KeyBundle instead. 1680 1681 \ingroup ProviderAPI 1682 */ 1683 class QCA_EXPORT PKCS12Context : public BasicContext 1684 { 1685 Q_OBJECT 1686 public: 1687 /** 1688 Standard constructor 1689 1690 \param p the Provider associated with this context 1691 */ 1692 PKCS12Context(Provider *p) 1693 : BasicContext(p, QStringLiteral("pkcs12")) 1694 { 1695 } 1696 1697 /** 1698 Create PKCS#12 DER output based on a set of input items 1699 1700 Returns an empty array on error. 1701 1702 \param name the friendly name of the data 1703 \param chain the certificate chain to store 1704 \param priv the private key to store 1705 \param passphrase the passphrase to encrypt the PKCS#12 data with 1706 */ 1707 virtual QByteArray toPKCS12(const QString &name, 1708 const QList<const CertContext *> &chain, 1709 const PKeyContext &priv, 1710 const SecureArray &passphrase) const = 0; 1711 1712 /** 1713 Read PKCS#12 DER input and convert it into a set of output items 1714 1715 The caller is responsible for deleting the returned items. 1716 1717 Returns QCA::ConvertGood if successful, otherwise some error 1718 value. 1719 1720 \param in the input data 1721 \param passphrase the passphrase needed to decrypt the input data 1722 \param name the destination string for the friendly name 1723 \param chain the destination list for the certificate chain 1724 \param priv address of a pointer to accept the private key 1725 */ 1726 virtual ConvertResult fromPKCS12(const QByteArray &in, 1727 const SecureArray &passphrase, 1728 QString *name, 1729 QList<CertContext *> *chain, 1730 PKeyContext **priv) const = 0; 1731 }; 1732 1733 /** 1734 \class PGPKeyContextProps qcaprovider.h QtCrypto 1735 1736 OpenPGP key properties 1737 1738 \note This class is part of the provider plugin interface and should not 1739 be used directly by applications. You probably want PGPKey instead. 1740 1741 For efficiency and simplicity, the members are directly accessed. 1742 1743 \ingroup ProviderAPI 1744 */ 1745 class QCA_EXPORT PGPKeyContextProps 1746 { 1747 public: 1748 /** 1749 The key id 1750 */ 1751 QString keyId; 1752 1753 /** 1754 List of user id strings for the key, the first one being the 1755 primary user id 1756 */ 1757 QStringList userIds; 1758 1759 /** 1760 True if this key is a secret key, otherwise false 1761 */ 1762 bool isSecret; 1763 1764 /** 1765 The time the key was created 1766 */ 1767 QDateTime creationDate; 1768 1769 /** 1770 The time the key expires 1771 */ 1772 QDateTime expirationDate; 1773 1774 /** 1775 The hex fingerprint of the key 1776 1777 The format is all lowercase with no spaces. 1778 */ 1779 QString fingerprint; 1780 1781 /** 1782 True if this key is in a keyring (and thus usable), otherwise 1783 false 1784 */ 1785 bool inKeyring; 1786 1787 /** 1788 True if this key is trusted (e.g. signed by the keyring owner or 1789 via some web-of-trust), otherwise false 1790 */ 1791 bool isTrusted; 1792 }; 1793 1794 /** 1795 \class PGPKeyContext qcaprovider.h QtCrypto 1796 1797 OpenPGP key provider 1798 1799 \note This class is part of the provider plugin interface and should not 1800 be used directly by applications. You probably want PGPKey instead. 1801 1802 \ingroup ProviderAPI 1803 */ 1804 class QCA_EXPORT PGPKeyContext : public BasicContext 1805 { 1806 Q_OBJECT 1807 public: 1808 /** 1809 Standard constructor 1810 1811 \param p the Provider associated with this context 1812 */ 1813 PGPKeyContext(Provider *p) 1814 : BasicContext(p, QStringLiteral("pgpkey")) 1815 { 1816 } 1817 1818 /** 1819 Returns a pointer to the properties of this key 1820 */ 1821 virtual const PGPKeyContextProps *props() const = 0; 1822 1823 /** 1824 Convert the key to binary format, and return the value 1825 */ 1826 virtual QByteArray toBinary() const = 0; 1827 1828 /** 1829 Convert the key to ascii-armored format, and return the value 1830 */ 1831 virtual QString toAscii() const = 0; 1832 1833 /** 1834 Read binary input and convert it into a key 1835 1836 Returns QCA::ConvertGood if successful, otherwise some error 1837 value. 1838 1839 \param a the input data 1840 */ 1841 virtual ConvertResult fromBinary(const QByteArray &a) = 0; 1842 1843 /** 1844 Read ascii-armored input and convert it into a key 1845 1846 Returns QCA::ConvertGood if successful, otherwise some error 1847 value. 1848 1849 \param s the input data 1850 */ 1851 virtual ConvertResult fromAscii(const QString &s) = 0; 1852 }; 1853 1854 /** 1855 \class KeyStoreEntryContext qcaprovider.h QtCrypto 1856 1857 KeyStoreEntry provider 1858 1859 \note This class is part of the provider plugin interface and should not 1860 be used directly by applications. You probably want KeyStoreEntry 1861 instead. 1862 1863 \ingroup ProviderAPI 1864 */ 1865 class QCA_EXPORT KeyStoreEntryContext : public BasicContext 1866 { 1867 Q_OBJECT 1868 public: 1869 /** 1870 Standard constructor 1871 1872 \param p the Provider associated with this context 1873 */ 1874 KeyStoreEntryContext(Provider *p) 1875 : BasicContext(p, QStringLiteral("keystoreentry")) 1876 { 1877 } 1878 1879 /** 1880 Returns the entry type 1881 */ 1882 virtual KeyStoreEntry::Type type() const = 0; 1883 1884 /** 1885 Returns the entry id 1886 1887 This id must be unique among all other entries in the same store. 1888 */ 1889 virtual QString id() const = 0; 1890 1891 /** 1892 Returns the name of this entry 1893 */ 1894 virtual QString name() const = 0; 1895 1896 /** 1897 Returns the id of the store that contains this entry 1898 */ 1899 virtual QString storeId() const = 0; 1900 1901 /** 1902 Returns the name of the store that contains this entry 1903 */ 1904 virtual QString storeName() const = 0; 1905 1906 /** 1907 Returns true if the private key of this entry is present for use 1908 */ 1909 virtual bool isAvailable() const; 1910 1911 /** 1912 Serialize the information about this entry 1913 1914 This allows the entry object to be restored later, even if the 1915 store that contains it is not present. 1916 1917 \sa KeyStoreListContext::entryPassive() 1918 */ 1919 virtual QString serialize() const = 0; 1920 1921 /** 1922 If this entry is of type KeyStoreEntry::TypeKeyBundle, this 1923 function returns the KeyBundle of the entry 1924 */ 1925 virtual KeyBundle keyBundle() const; 1926 1927 /** 1928 If this entry is of type KeyStoreEntry::TypeCertificate, this 1929 function returns the Certificate of the entry 1930 */ 1931 virtual Certificate certificate() const; 1932 1933 /** 1934 If this entry is of type KeyStoreEntry::TypeCRL, this function 1935 returns the CRL of the entry 1936 */ 1937 virtual CRL crl() const; 1938 1939 /** 1940 If this entry is of type KeyStoreEntry::TypePGPSecretKey, this 1941 function returns the secret PGPKey of the entry 1942 */ 1943 virtual PGPKey pgpSecretKey() const; 1944 1945 /** 1946 If this entry is of type KeyStoreEntry::TypePGPPublicKey or 1947 KeyStoreEntry::TypePGPSecretKey, this function returns the public 1948 PGPKey of the entry 1949 */ 1950 virtual PGPKey pgpPublicKey() const; 1951 1952 /** 1953 Attempt to ensure the private key of this entry is usable and 1954 accessible, potentially prompting the user and/or performing a 1955 login to a token device. Returns true if the entry is now 1956 accessible, or false if the entry cannot be made accessible. 1957 1958 This function is blocking. 1959 */ 1960 virtual bool ensureAccess(); 1961 }; 1962 1963 /** 1964 \class KeyStoreListContext qcaprovider.h QtCrypto 1965 1966 KeyStore provider 1967 1968 \note This class is part of the provider plugin interface and should not 1969 be used directly by applications. You probably want KeyStore instead. 1970 1971 \ingroup ProviderAPI 1972 */ 1973 class QCA_EXPORT KeyStoreListContext : public Provider::Context 1974 { 1975 Q_OBJECT 1976 public: 1977 /** 1978 Standard constructor 1979 1980 \param p the Provider associated with this context 1981 */ 1982 KeyStoreListContext(Provider *p) 1983 : Provider::Context(p, QStringLiteral("keystorelist")) 1984 { 1985 } 1986 1987 /** 1988 Starts the keystore provider 1989 */ 1990 virtual void start(); 1991 1992 /** 1993 Enables or disables update events 1994 1995 The updated() and storeUpdated() signals might not be emitted if 1996 updates are not enabled. 1997 1998 \param enabled whether update notifications are enabled (true) or disabled (false) 1999 */ 2000 virtual void setUpdatesEnabled(bool enabled); 2001 2002 /** 2003 Returns a list of integer context ids, each representing a 2004 keystore instance 2005 2006 If a keystore becomes unavailable and then later becomes 2007 available again (for example, if a smart card is removed and 2008 then the same one is inserted again), the integer context id 2009 must be different than last time. 2010 */ 2011 virtual QList<int> keyStores() = 0; 2012 2013 /** 2014 Returns the type of the specified store, or -1 if the integer 2015 context id is invalid 2016 2017 \param id the id for the store context 2018 */ 2019 virtual KeyStore::Type type(int id) const = 0; 2020 2021 /** 2022 Returns the string id of the store, or an empty string if the 2023 integer context id is invalid 2024 2025 The string id of the store should be unique to a single store, and 2026 it should persist between availability/unavailability. For 2027 example, a smart card that is removed and inserted again should 2028 have the same string id (despite having a new integer context id). 2029 2030 \param id the id for the store context 2031 */ 2032 virtual QString storeId(int id) const = 0; 2033 2034 /** 2035 Returns the friendly name of the store, or an empty string if the 2036 integer context id is invalid 2037 2038 \param id the id for the store context 2039 */ 2040 virtual QString name(int id) const = 0; 2041 2042 /** 2043 Returns true if the store is read-only 2044 2045 If the integer context id is invalid, this function should return 2046 true. 2047 2048 \param id the id for the store context 2049 */ 2050 virtual bool isReadOnly(int id) const; 2051 2052 /** 2053 Returns the types supported by the store, or an empty list if the 2054 integer context id is invalid 2055 2056 This function should return all supported types, even if the store 2057 doesn't actually contain entries for all of the types. 2058 2059 \param id the id for the store context 2060 */ 2061 virtual QList<KeyStoreEntry::Type> entryTypes(int id) const = 0; 2062 2063 /** 2064 Returns the entries of the store, or an empty list if the integer 2065 context id is invalid 2066 2067 The caller is responsible for deleting the returned entry objects. 2068 2069 \param id the id for the store context 2070 */ 2071 virtual QList<KeyStoreEntryContext *> entryList(int id) = 0; 2072 2073 /** 2074 Returns a single entry in the store, if the entry id is already 2075 known. If the entry does not exist, the function returns 0. 2076 2077 The caller is responsible for deleting the returned entry object. 2078 2079 \param id the id for the store context 2080 \param entryId the entry to retrieve 2081 */ 2082 virtual KeyStoreEntryContext *entry(int id, const QString &entryId); 2083 2084 /** 2085 Returns a single entry, created from the serialization string of 2086 a previous entry (using KeyStoreEntryContext::serialize()). If 2087 the serialization string cannot be parsed by this provider, or the 2088 entry cannot otherwise be created, the function returns 0. 2089 2090 The caller is responsible for deleting the returned entry object. 2091 2092 This function must be thread-safe. 2093 2094 \param serialized the serialized data to create the entry from 2095 */ 2096 virtual KeyStoreEntryContext *entryPassive(const QString &serialized); 2097 2098 /** 2099 Write a KeyBundle to the store 2100 2101 Returns the entry id of the new item, or an empty string if there 2102 was an error writing the item. 2103 2104 \param id the id for the store context 2105 \param kb the key bundle to add to the store 2106 */ 2107 virtual QString writeEntry(int id, const KeyBundle &kb); 2108 2109 /** 2110 Write a Certificate to the store 2111 2112 Returns the entry id of the new item, or an empty string if there 2113 was an error writing the item. 2114 2115 \param id the id for the store context 2116 \param cert the certificate to add to the store 2117 */ 2118 virtual QString writeEntry(int id, const Certificate &cert); 2119 2120 /** 2121 Write a CRL to the store 2122 2123 Returns the entry id of the new item, or an empty string if there 2124 was an error writing the item. 2125 2126 \param id the id for the store context 2127 \param crl the revocation list to add to the store 2128 */ 2129 virtual QString writeEntry(int id, const CRL &crl); 2130 2131 /** 2132 Write a PGPKey to the store 2133 2134 Returns the entry id of the new item, or an empty string if there 2135 was an error writing the item. 2136 2137 \param id the id for the store context 2138 \param key the PGP key to add to the store 2139 */ 2140 virtual QString writeEntry(int id, const PGPKey &key); 2141 2142 /** 2143 Remove an entry from the store 2144 2145 Returns true if the entry is successfully removed, otherwise 2146 false. 2147 2148 \param id the id for the store context 2149 \param entryId the entry to remove from the store 2150 */ 2151 virtual bool removeEntry(int id, const QString &entryId); 2152 2153 Q_SIGNALS: 2154 /** 2155 Emit this when the provider is busy looking for keystores. The 2156 provider goes into a busy state when it has reason to believe 2157 there are keystores present, but it still needs to check or query 2158 some devices to see for sure. 2159 2160 For example, if a smart card is inserted, then the provider may 2161 immediately go into a busy state upon detecting the insert. 2162 However, it may take some seconds before the smart card 2163 information can be queried and reported by the provider. Once 2164 the card is queried successfully, the provider would leave the 2165 busy state and report the new keystore. 2166 2167 When this object is first started with start(), it is assumed to 2168 be in the busy state, so there is no need to emit this signal at 2169 the beginning. 2170 */ 2171 void busyStart(); 2172 2173 /** 2174 Emit this to leave the busy state 2175 2176 When this object is first started with start(), it is assumed to 2177 be in the busy state. You must emit busyEnd() at some point, or 2178 QCA will never ask you about keystores. 2179 */ 2180 void busyEnd(); 2181 2182 /** 2183 Indicates the list of keystores has changed, and that QCA should 2184 call keyStores() to obtain the latest list 2185 */ 2186 void updated(); 2187 2188 /** 2189 Emitted when there is diagnostic text to report 2190 2191 \param str the diagnostic text 2192 */ 2193 void diagnosticText(const QString &str); 2194 2195 /** 2196 Indicates that the entry list of a keystore has changed (entries 2197 added, removed, or modified) 2198 2199 \param id the id of the key store that has changed 2200 */ 2201 void storeUpdated(int id); 2202 }; 2203 2204 /** 2205 \class TLSSessionContext qcaprovider.h QtCrypto 2206 2207 TLS "session" provider 2208 2209 \note This class is part of the provider plugin interface and should not 2210 be used directly by applications. You probably want TLSSession instead. 2211 2212 \ingroup ProviderAPI 2213 */ 2214 class QCA_EXPORT TLSSessionContext : public BasicContext 2215 { 2216 Q_OBJECT 2217 public: 2218 /** 2219 Standard constructor 2220 2221 \param p the Provider associated with this context 2222 */ 2223 TLSSessionContext(Provider *p) 2224 : BasicContext(p, QStringLiteral("tlssession")) 2225 { 2226 } 2227 }; 2228 2229 /** 2230 \class TLSContext qcaprovider.h QtCrypto 2231 2232 TLS provider 2233 2234 \note This class is part of the provider plugin interface and should not 2235 be used directly by applications. You probably want TLS instead. 2236 2237 \ingroup ProviderAPI 2238 */ 2239 class QCA_EXPORT TLSContext : public Provider::Context 2240 { 2241 Q_OBJECT 2242 public: 2243 /** 2244 \class QCA::TLSContext::SessionInfo qcaprovider.h QtCrypto 2245 2246 Information about an active TLS connection 2247 2248 For efficiency and simplicity, the members are directly accessed. 2249 2250 \ingroup ProviderAPI 2251 */ 2252 class SessionInfo 2253 { 2254 public: 2255 /** 2256 True if the TLS connection is compressed, otherwise false 2257 */ 2258 bool isCompressed; 2259 2260 /** 2261 The TLS protocol version being used for this connection 2262 */ 2263 TLS::Version version; 2264 2265 /** 2266 The cipher suite being used for this connection 2267 2268 \sa TLSContext::supportedCipherSuites() 2269 */ 2270 QString cipherSuite; 2271 2272 /** 2273 The bit size of the cipher used for this connection 2274 */ 2275 int cipherBits; 2276 2277 /** 2278 The maximum bit size possible of the cipher used for this 2279 connection 2280 */ 2281 int cipherMaxBits; 2282 2283 /** 2284 Pointer to the id of this TLS session, for use with 2285 resuming 2286 */ 2287 TLSSessionContext *id; 2288 }; 2289 2290 /** 2291 Result of a TLS operation 2292 */ 2293 enum Result 2294 { 2295 Success, ///< Operation completed 2296 Error, ///< Operation failed 2297 Continue ///< More data needed to complete operation 2298 }; 2299 2300 /** 2301 Standard constructor 2302 2303 \param p the Provider associated with this context 2304 \param type the name of the type of feature that supported by this context 2305 */ 2306 TLSContext(Provider *p, const QString &type) 2307 : Provider::Context(p, type) 2308 { 2309 } 2310 2311 /** 2312 Reset the object to its initial state 2313 */ 2314 virtual void reset() = 0; 2315 2316 /** 2317 Returns a list of supported cipher suites for the specified 2318 SSL/TLS version. The cipher suites are specified as strings, for 2319 example: "TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA" (without quotes). 2320 2321 \param version the version of TLS to search for 2322 */ 2323 virtual QStringList supportedCipherSuites(const TLS::Version &version) const = 0; 2324 2325 /** 2326 Returns true if the provider supports compression 2327 */ 2328 virtual bool canCompress() const = 0; 2329 2330 /** 2331 Returns true if the provider supports server name indication 2332 */ 2333 virtual bool canSetHostName() const = 0; 2334 2335 /** 2336 Returns the maximum SSF supported by this provider 2337 */ 2338 virtual int maxSSF() const = 0; 2339 2340 /** 2341 Configure a new session 2342 2343 This function will be called before any other configuration 2344 functions. 2345 2346 \param serverMode whether to operate as a server (true) or client (false) 2347 \param hostName the hostname to use 2348 \param compress whether to compress (true) or not (false) 2349 */ 2350 virtual void setup(bool serverMode, const QString &hostName, bool compress) = 0; 2351 2352 /** 2353 Set the constraints of the session using SSF values 2354 2355 This function will be called before start(). 2356 2357 \param minSSF the minimum strength factor that is acceptable 2358 \param maxSSF the maximum strength factor that is acceptable 2359 */ 2360 virtual void setConstraints(int minSSF, int maxSSF) = 0; 2361 2362 /** 2363 \overload 2364 2365 Set the constraints of the session using a cipher suite list 2366 2367 This function will be called before start(). 2368 2369 \param cipherSuiteList the list of cipher suites that may be used for 2370 this session. 2371 2372 \sa supportedCipherSuites 2373 */ 2374 virtual void setConstraints(const QStringList &cipherSuiteList) = 0; 2375 2376 /** 2377 Set the list of trusted certificates 2378 2379 This function may be called at any time. 2380 2381 \param trusted the trusted certificates and CRLs to be used. 2382 */ 2383 virtual void setTrustedCertificates(const CertificateCollection &trusted) = 0; 2384 2385 /** 2386 Set the list of acceptable issuers 2387 2388 This function may be called at any time. 2389 2390 This function is for server mode only. 2391 2392 \param issuerList the list of issuers that may be used 2393 */ 2394 virtual void setIssuerList(const QList<CertificateInfoOrdered> &issuerList) = 0; 2395 2396 /** 2397 Set the local certificate 2398 2399 This function may be called at any time. 2400 2401 \param cert the certificate and associated trust chain 2402 \param key the private key for the local certificate 2403 */ 2404 virtual void setCertificate(const CertificateChain &cert, const PrivateKey &key) = 0; 2405 2406 /** 2407 Set the TLS session id, for session resuming 2408 2409 This function will be called before start(). 2410 2411 \param id the session identification 2412 */ 2413 virtual void setSessionId(const TLSSessionContext &id) = 0; 2414 2415 /** 2416 Sets the session to the shutdown state. 2417 2418 The actual shutdown operation will happen at a future call to 2419 update(). 2420 2421 This function is for normal TLS only (not DTLS). 2422 */ 2423 virtual void shutdown() = 0; 2424 2425 /** 2426 Set the maximum transmission unit size 2427 2428 This function is for DTLS only. 2429 2430 \param size the maximum number of bytes in a datagram 2431 */ 2432 virtual void setMTU(int size); 2433 2434 /** 2435 Begins the session, starting with the handshake 2436 2437 This function returns immediately, and completion is signaled with 2438 the resultsReady() signal. 2439 2440 On completion, the result() function will return Success if the 2441 TLS session is able to begin, or Error if there is a failure to 2442 initialize the TLS subsystem. If successful, the session is now 2443 in the handshake state, and update() will be called repeatedly 2444 until the session ends. 2445 */ 2446 virtual void start() = 0; 2447 2448 /** 2449 Performs one iteration of the TLS session processing 2450 2451 This function returns immediately, and completion is signaled with 2452 the resultsReady() signal. 2453 2454 If the session is in a handshake state, result() and to_net() will 2455 be valid. If result() is Success, then the session is now in the 2456 connected state. 2457 2458 If the session is in a shutdown state, result() and to_net() will 2459 be valid. If result() is Success, then the session has ended. 2460 2461 If the session is in a connected state, result(), to_net(), 2462 encoded(), to_app(), and eof() are valid. The result() function 2463 will return Success or Error. Note that eof() does not apply 2464 to DTLS. 2465 2466 For DTLS, this function operates with single packets. Many 2467 update() operations must be performed repeatedly to exchange 2468 multiple packets. 2469 2470 \param from_net the data from the "other side" of the connection 2471 \param from_app the data from the application of the protocol 2472 */ 2473 virtual void update(const QByteArray &from_net, const QByteArray &from_app) = 0; 2474 2475 /** 2476 Waits for a start() or update() operation to complete. In this 2477 case, the resultsReady() signal is not emitted. Returns true if 2478 the operation completed or false if this function times out. 2479 2480 This function is blocking. 2481 2482 \param msecs number of milliseconds to wait (-1 to wait forever) 2483 */ 2484 virtual bool waitForResultsReady(int msecs) = 0; 2485 2486 /** 2487 Returns the result code of an operation 2488 */ 2489 virtual Result result() const = 0; 2490 2491 /** 2492 Returns data that should be sent across the network 2493 */ 2494 virtual QByteArray to_net() = 0; 2495 2496 /** 2497 Returns the number of bytes of plaintext data that is encoded 2498 inside of to_net() 2499 */ 2500 virtual int encoded() const = 0; 2501 2502 /** 2503 Returns data that is decoded from the network and should be 2504 processed by the application 2505 */ 2506 virtual QByteArray to_app() = 0; 2507 2508 /** 2509 Returns true if the peer has closed the stream 2510 */ 2511 virtual bool eof() const = 0; 2512 2513 /** 2514 Returns true if the TLS client hello has been received 2515 2516 This is only valid if a handshake is in progress or 2517 completed. 2518 */ 2519 virtual bool clientHelloReceived() const = 0; 2520 2521 /** 2522 Returns true if the TLS server hello has been received 2523 2524 This is only valid if a handshake is in progress or completed. 2525 */ 2526 virtual bool serverHelloReceived() const = 0; 2527 2528 /** 2529 Returns the host name sent by the client using server name 2530 indication (server mode only) 2531 2532 This is only valid if a handshake is in progress or completed. 2533 */ 2534 virtual QString hostName() const = 0; 2535 2536 /** 2537 Returns true if the peer is requesting a certificate 2538 2539 This is only valid if a handshake is in progress or completed. 2540 */ 2541 virtual bool certificateRequested() const = 0; 2542 2543 /** 2544 Returns the issuer list sent by the server (client mode only) 2545 2546 This is only valid if a handshake is in progress or completed. 2547 */ 2548 virtual QList<CertificateInfoOrdered> issuerList() const = 0; 2549 2550 /** 2551 Returns the QCA::Validity of the peer certificate 2552 2553 This is only valid if a handshake is completed. 2554 */ 2555 virtual Validity peerCertificateValidity() const = 0; 2556 2557 /** 2558 Returns the peer certificate chain 2559 2560 This is only valid if a handshake is completed. 2561 */ 2562 virtual CertificateChain peerCertificateChain() const = 0; 2563 2564 /** 2565 Returns information about the active TLS session 2566 2567 This is only valid if a handshake is completed. 2568 */ 2569 virtual SessionInfo sessionInfo() const = 0; 2570 2571 /** 2572 Returns any unprocessed network input data 2573 2574 This is only valid after a successful shutdown. 2575 */ 2576 virtual QByteArray unprocessed() = 0; 2577 2578 Q_SIGNALS: 2579 /** 2580 Emit this when a start() or update() operation has completed. 2581 */ 2582 void resultsReady(); 2583 2584 /** 2585 Emit this to force the application to call update(), even with 2586 empty arguments. 2587 */ 2588 void dtlsTimeout(); 2589 }; 2590 2591 /** 2592 \class SASLContext qcaprovider.h QtCrypto 2593 2594 SASL provider 2595 2596 \note This class is part of the provider plugin interface and should not 2597 be used directly by applications. You probably want SASL instead. 2598 2599 \ingroup ProviderAPI 2600 */ 2601 class QCA_EXPORT SASLContext : public Provider::Context 2602 { 2603 Q_OBJECT 2604 public: 2605 /** 2606 \class QCA::SASLContext::HostPort qcaprovider.h QtCrypto 2607 2608 Convenience class to hold an IP address and an associated port 2609 2610 For efficiency and simplicity, the members are directly accessed. 2611 2612 \ingroup ProviderAPI 2613 */ 2614 class HostPort 2615 { 2616 public: 2617 /** 2618 The IP address 2619 */ 2620 QString addr; 2621 2622 /** 2623 The port 2624 */ 2625 quint16 port; 2626 }; 2627 2628 /** 2629 Result of a SASL operation 2630 */ 2631 enum Result 2632 { 2633 Success, ///< Operation completed 2634 Error, ///< Operation failed 2635 Params, ///< Parameters are needed to complete authentication 2636 AuthCheck, ///< Client login can be inspected (server only) 2637 Continue ///< More steps needed to complete authentication 2638 }; 2639 2640 /** 2641 Standard constructor 2642 2643 \param p the Provider associated with this context 2644 */ 2645 SASLContext(Provider *p) 2646 : Provider::Context(p, QStringLiteral("sasl")) 2647 { 2648 } 2649 2650 /** 2651 Reset the object to its initial state 2652 */ 2653 virtual void reset() = 0; 2654 2655 /** 2656 Configure a new session 2657 2658 This function will be called before any other configuration 2659 functions. 2660 2661 \param service the name of the network service being provided by 2662 this application, which can be used by the SASL system for policy 2663 control. Examples: "imap", "xmpp" 2664 \param host the hostname that the application is interacting with 2665 or as 2666 \param local pointer to a HostPort representing the local end of a 2667 network socket, or 0 if this information is unknown or not 2668 available 2669 \param remote pointer to a HostPort representing the peer end of a 2670 network socket, or 0 if this information is unknown or not 2671 available 2672 \param ext_id the id to be used for SASL EXTERNAL (client only) 2673 \param ext_ssf the SSF of the external authentication channel 2674 (client only) 2675 */ 2676 virtual void setup(const QString &service, 2677 const QString &host, 2678 const HostPort *local, 2679 const HostPort *remote, 2680 const QString &ext_id, 2681 int ext_ssf) = 0; 2682 2683 /** 2684 Set the constraints of the session using SSF values 2685 2686 This function will be called before startClient() or 2687 startServer(). 2688 2689 \param f the flags to use 2690 \param minSSF the minimum strength factor that is acceptable 2691 \param maxSSF the maximum strength factor that is acceptable 2692 */ 2693 virtual void setConstraints(SASL::AuthFlags f, int minSSF, int maxSSF) = 0; 2694 2695 /** 2696 Begins the session in client mode, starting with the 2697 authentication 2698 2699 This function returns immediately, and completion is signaled with 2700 the resultsReady() signal. 2701 2702 On completion, result(), mech(), haveClientInit(), and stepData() 2703 will be valid. If result() is Success, then the session is now in 2704 the connected state. 2705 2706 \param mechlist the list of mechanisms 2707 \param allowClientSendFirst whether the client sends first (true) or the server 2708 sends first (false) 2709 */ 2710 virtual void startClient(const QStringList &mechlist, bool allowClientSendFirst) = 0; 2711 2712 /** 2713 Begins the session in server mode, starting with the 2714 authentication 2715 2716 This function returns immediately, and completion is signaled with 2717 the resultsReady() signal. 2718 2719 On completion, result() and mechlist() will be valid. The 2720 result() function will return Success or Error. If the result is 2721 Success, then serverFirstStep() will be called next. 2722 2723 \param realm the realm to authenticate in 2724 \param disableServerSendLast whether the client sends first (true) 2725 or the server sends first (false) 2726 */ 2727 virtual void startServer(const QString &realm, bool disableServerSendLast) = 0; 2728 2729 /** 2730 Finishes server startup 2731 2732 This function returns immediately, and completion is signaled with 2733 the resultsReady() signal. 2734 2735 On completion, result() and stepData() will be valid. If result() 2736 is Success, then the session is now in the connected state. 2737 2738 \param mech the mechanism to use 2739 \param clientInit initial data from the client, or 0 if there is 2740 no such data 2741 */ 2742 virtual void serverFirstStep(const QString &mech, const QByteArray *clientInit) = 0; 2743 2744 /** 2745 Perform another step of the SASL authentication 2746 2747 This function returns immediately, and completion is signaled with 2748 the resultsReady() signal. 2749 2750 On completion, result() and stepData() will be valid. 2751 2752 \param from_net the data from the "other side" of the protocol 2753 to be used for the next step. 2754 */ 2755 virtual void nextStep(const QByteArray &from_net) = 0; 2756 2757 /** 2758 Attempt the most recent operation again. This is used if the 2759 result() of an operation is Params or AuthCheck. 2760 2761 This function returns immediately, and completion is signaled with 2762 the resultsReady() signal. 2763 2764 On completion, result() and stepData() will be valid. 2765 */ 2766 virtual void tryAgain() = 0; 2767 2768 /** 2769 Performs one iteration of the SASL security layer processing 2770 2771 This function returns immediately, and completion is signaled with 2772 the resultsReady() signal. 2773 2774 On completion, result(), to_net(), encoded(), and to_app() will be 2775 valid. The result() function will return Success or Error. 2776 2777 \param from_net the data from the "other side" of the protocol 2778 \param from_app the data from the application of the protocol 2779 */ 2780 virtual void update(const QByteArray &from_net, const QByteArray &from_app) = 0; 2781 2782 /** 2783 Waits for a startClient(), startServer(), serverFirstStep(), 2784 nextStep(), tryAgain(), or update() operation to complete. In 2785 this case, the resultsReady() signal is not emitted. Returns true 2786 if the operation completed or false if this function times out. 2787 2788 This function is blocking. 2789 2790 \param msecs number of milliseconds to wait (-1 to wait forever) 2791 */ 2792 virtual bool waitForResultsReady(int msecs) = 0; 2793 2794 /** 2795 Returns the result code of an operation 2796 */ 2797 virtual Result result() const = 0; 2798 2799 /** 2800 Returns the mechanism list (server mode only) 2801 */ 2802 virtual QStringList mechlist() const = 0; 2803 2804 /** 2805 Returns the mechanism selected 2806 */ 2807 virtual QString mech() const = 0; 2808 2809 /** 2810 Returns true if the client has initialization data 2811 */ 2812 virtual bool haveClientInit() const = 0; 2813 2814 /** 2815 Returns an authentication payload for to be transmitted over the 2816 network 2817 */ 2818 virtual QByteArray stepData() const = 0; 2819 2820 /** 2821 Returns data that should be sent across the network (for the 2822 security layer) 2823 */ 2824 virtual QByteArray to_net() = 0; 2825 2826 /** 2827 Returns the number of bytes of plaintext data that is encoded 2828 inside of to_net() 2829 */ 2830 virtual int encoded() const = 0; 2831 2832 /** 2833 Returns data that is decoded from the network and should be 2834 processed by the application 2835 */ 2836 virtual QByteArray to_app() = 0; 2837 2838 /** 2839 Returns the SSF of the active SASL session 2840 2841 This is only valid after authentication success. 2842 */ 2843 virtual int ssf() const = 0; 2844 2845 /** 2846 Returns the reason for failure, if the authentication was not 2847 successful. 2848 2849 This is only valid after authentication failure. 2850 */ 2851 virtual SASL::AuthCondition authCondition() const = 0; 2852 2853 /** 2854 Returns the needed/optional client parameters 2855 2856 This is only valid after receiving the Params result code. 2857 */ 2858 virtual SASL::Params clientParams() const = 0; 2859 2860 /** 2861 Set some of the client parameters (pass 0 to not set a field) 2862 2863 \param user the user name 2864 \param authzid the authorization name / role 2865 \param pass the password 2866 \param realm the realm to authenticate in 2867 */ 2868 virtual void 2869 setClientParams(const QString *user, const QString *authzid, const SecureArray *pass, const QString *realm) = 0; 2870 2871 /** 2872 Returns the realm list (client mode only) 2873 2874 This is only valid after receiving the Params result code and 2875 SASL::Params::canSendRealm is set to true. 2876 */ 2877 virtual QStringList realmlist() const = 0; 2878 2879 /** 2880 Returns the username attempting to authenticate (server mode only) 2881 2882 This is only valid after receiving the AuthCheck result code. 2883 */ 2884 virtual QString username() const = 0; 2885 2886 /** 2887 Returns the authzid attempting to authorize (server mode only) 2888 2889 This is only valid after receiving the AuthCheck result code. 2890 */ 2891 virtual QString authzid() const = 0; 2892 2893 Q_SIGNALS: 2894 /** 2895 Emit this when a startClient(), startServer(), serverFirstStep(), 2896 nextStep(), tryAgain(), or update() operation has completed. 2897 */ 2898 void resultsReady(); 2899 }; 2900 2901 /** 2902 \class MessageContext qcaprovider.h QtCrypto 2903 2904 SecureMessage provider 2905 2906 \note This class is part of the provider plugin interface and should not 2907 be used directly by applications. You probably want SecureMessage 2908 instead. 2909 2910 \ingroup ProviderAPI 2911 */ 2912 class QCA_EXPORT MessageContext : public Provider::Context 2913 { 2914 Q_OBJECT 2915 public: 2916 /** 2917 The type of operation being performed 2918 */ 2919 enum Operation 2920 { 2921 Encrypt, ///< Encrypt operation 2922 Decrypt, ///< Decrypt (or Decrypt and Verify) operation 2923 Sign, ///< Sign operation 2924 Verify, ///< Verify operation 2925 SignAndEncrypt ///< Sign and Encrypt operation 2926 }; 2927 2928 /** 2929 Standard constructor 2930 2931 \param p the Provider associated with this context 2932 \param type the name of the type of secure message to be created 2933 */ 2934 MessageContext(Provider *p, const QString &type) 2935 : Provider::Context(p, type) 2936 { 2937 } 2938 2939 /** 2940 Returns true if the provider supports multiple signers for 2941 signature creation or signature verification 2942 */ 2943 virtual bool canSignMultiple() const = 0; 2944 2945 /** 2946 The type of secure message (e.g. PGP or CMS) 2947 */ 2948 virtual SecureMessage::Type type() const = 0; 2949 2950 /** 2951 Reset the object to its initial state 2952 */ 2953 virtual void reset() = 0; 2954 2955 /** 2956 Configure a new encrypting operation 2957 2958 \param keys the keys to be used for encryption. 2959 */ 2960 virtual void setupEncrypt(const SecureMessageKeyList &keys) = 0; 2961 2962 /** 2963 Configure a new signing operation 2964 2965 \param keys the keys to use for signing 2966 \param m the mode to sign in 2967 \param bundleSigner whether to bundle the signing keys (true) or not (false) 2968 \param smime whether to use smime format (true) or not (false) 2969 */ 2970 virtual void 2971 setupSign(const SecureMessageKeyList &keys, SecureMessage::SignMode m, bool bundleSigner, bool smime) = 0; 2972 2973 /** 2974 Configure a new verify operation 2975 2976 \param detachedSig the detached signature to use (if applicable) for verification 2977 */ 2978 virtual void setupVerify(const QByteArray &detachedSig) = 0; 2979 2980 /** 2981 Begins the secure message operation 2982 2983 This function returns immediately. 2984 2985 If there is input data, update() will be called (potentially 2986 repeatedly) afterwards. Emit updated() if there is data to 2987 read, if input data has been accepted, or if the operation has 2988 finished. 2989 2990 \param f the format of the message to be produced 2991 \param op the operation to be performed 2992 */ 2993 virtual void start(SecureMessage::Format f, Operation op) = 0; 2994 2995 /** 2996 Provide input to the message operation 2997 2998 \param in the data to use for the message operation 2999 */ 3000 virtual void update(const QByteArray &in) = 0; 3001 3002 /** 3003 Extract output from the message operation 3004 */ 3005 virtual QByteArray read() = 0; 3006 3007 /** 3008 Returns the number of input bytes accepted since the last call to 3009 update() 3010 */ 3011 virtual int written() = 0; 3012 3013 /** 3014 Indicates the end of input 3015 */ 3016 virtual void end() = 0; 3017 3018 /** 3019 Returns true if the operation has finished, otherwise false 3020 */ 3021 virtual bool finished() const = 0; 3022 3023 /** 3024 Waits for the secure message operation to complete. In this case, 3025 the updated() signal is not emitted. Returns true if the 3026 operation completed or false if this function times out. 3027 3028 This function is blocking. 3029 3030 \param msecs number of milliseconds to wait (-1 to wait forever) 3031 */ 3032 virtual bool waitForFinished(int msecs) = 0; 3033 3034 /** 3035 Returns true if the operation was successful 3036 3037 This is only valid if the operation has finished. 3038 */ 3039 virtual bool success() const = 0; 3040 3041 /** 3042 Returns the reason for failure, if the operation was not 3043 successful 3044 3045 This is only valid if the operation has finished. 3046 */ 3047 virtual SecureMessage::Error errorCode() const = 0; 3048 3049 /** 3050 Returns the signature, in the case of a detached signature 3051 operation 3052 3053 This is only valid if the operation has finished. 3054 */ 3055 virtual QByteArray signature() const = 0; 3056 3057 /** 3058 Returns the name of the hash used to generate the signature, in 3059 the case of a signature operation 3060 3061 This is only valid if the operation has finished. 3062 */ 3063 virtual QString hashName() const = 0; 3064 3065 /** 3066 Returns a list of signatures, in the case of a verify or decrypt 3067 and verify operation 3068 3069 This is only valid if the operation has finished. 3070 */ 3071 virtual SecureMessageSignatureList signers() const = 0; 3072 3073 /** 3074 Returns any diagnostic text for the operation, potentially useful 3075 to show the user in the event the operation is unsuccessful. For 3076 example, this could be the stderr output of gpg. 3077 3078 This is only valid if the operation has finished. 3079 */ 3080 virtual QString diagnosticText() const; 3081 3082 Q_SIGNALS: 3083 /** 3084 Emitted when there is data to read, if input data has been 3085 accepted, or if the operation has finished 3086 */ 3087 void updated(); 3088 }; 3089 3090 /** 3091 \class SMSContext qcaprovider.h QtCrypto 3092 3093 SecureMessageSystem provider 3094 3095 \note This class is part of the provider plugin interface and should not 3096 be used directly by applications. You probably want SecureMessageSystem 3097 instead. 3098 3099 \ingroup ProviderAPI 3100 */ 3101 class QCA_EXPORT SMSContext : public BasicContext 3102 { 3103 Q_OBJECT 3104 public: 3105 /** 3106 Standard constructor 3107 3108 \param p the provider associated with this context 3109 \param type the name of the type of secure message system 3110 */ 3111 SMSContext(Provider *p, const QString &type) 3112 : BasicContext(p, type) 3113 { 3114 } 3115 3116 /** 3117 Set the trusted certificates and for this secure message system, 3118 to be used for validation 3119 3120 The collection may also contain CRLs. 3121 3122 This function is only valid for CMS. 3123 3124 \param trusted a set of trusted certificates and CRLs. 3125 */ 3126 virtual void setTrustedCertificates(const CertificateCollection &trusted); 3127 3128 /** 3129 Set the untrusted certificates and CRLs for this secure message 3130 system, to be used for validation 3131 3132 This function is only valid for CMS. 3133 3134 \param untrusted a set of untrusted certificates and CRLs. 3135 */ 3136 virtual void setUntrustedCertificates(const CertificateCollection &untrusted); 3137 3138 /** 3139 Set the private keys for this secure message system, to be used 3140 for decryption 3141 3142 This function is only valid for CMS. 3143 3144 \param keys the keys to be used for decryption 3145 */ 3146 virtual void setPrivateKeys(const QList<SecureMessageKey> &keys); 3147 3148 /** 3149 Create a new message object for this system. The caller is 3150 responsible for deleting it. 3151 */ 3152 virtual MessageContext *createMessage() = 0; 3153 }; 3154 3155 } 3156 #endif 3157 3158 #endif