File indexing completed on 2024-04-28 04:43:40
0001 /* 0002 * qca_core.h - Qt Cryptographic Architecture 0003 * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com> 0004 * Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net> 0005 * Copyright (C) 2014-2016 Ivan Romanov <drizt@land.ru> 0006 * 0007 * This library is free software; you can redistribute it and/or 0008 * modify it under the terms of the GNU Lesser General Public 0009 * License as published by the Free Software Foundation; either 0010 * version 2.1 of the License, or (at your option) any later version. 0011 * 0012 * This library is distributed in the hope that it will be useful, 0013 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0015 * Lesser General Public License for more details. 0016 * 0017 * You should have received a copy of the GNU Lesser General Public 0018 * License along with this library; if not, write to the Free Software 0019 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 0020 * 02110-1301 USA 0021 * 0022 */ 0023 0024 /** 0025 \file qca_core.h 0026 0027 Header file for core %QCA infrastructure 0028 0029 \note You should not use this header directly from an 0030 application. You should just use <tt> \#include \<QtCrypto> 0031 </tt> instead. 0032 */ 0033 0034 #ifndef QCA_CORE_H 0035 #define QCA_CORE_H 0036 0037 #include "qca_export.h" 0038 #include "qca_support.h" 0039 #include "qca_tools.h" 0040 #include "qca_version.h" 0041 #include <QList> 0042 #include <QSharedData> 0043 #include <QSharedDataPointer> 0044 #include <QString> 0045 #include <QStringList> 0046 0047 /** 0048 The current version of %QCA. 0049 0050 This is equivalent to ::QCA_VERSION, except it provides 0051 a runtime check of the version of %QCA that is being used. 0052 */ 0053 QCA_EXPORT int qcaVersion(); 0054 0055 /** 0056 The current version of %QCA. 0057 0058 This is equivalent to ::QCA_VERSION_STR, except it provides 0059 a runtime check of the version of %QCA that is being used. 0060 */ 0061 QCA_EXPORT const char *qcaVersionStr(); 0062 0063 /** 0064 The current version of %QCA. 0065 0066 This is equivalent to ::QCA_MAJOR_VERSION, except it provides 0067 a runtime check of the version of %QCA that is being used. 0068 */ 0069 QCA_EXPORT int qcaMajorVersion(); 0070 0071 /** 0072 The current version of %QCA. 0073 0074 This is equivalent to ::QCA_MINOR_VERSION, except it provides 0075 a runtime check of the version of %QCA that is being used. 0076 */ 0077 QCA_EXPORT int qcaMinorVersion(); 0078 0079 /** 0080 The current version of %QCA. 0081 0082 This is equivalent to ::QCA_PATCH_VERSION, except it provides 0083 a runtime check of the version of %QCA that is being used. 0084 */ 0085 QCA_EXPORT int qcaPatchVersion(); 0086 0087 /** 0088 QCA - the Qt Cryptographic Architecture 0089 */ 0090 namespace QCA { 0091 0092 class Provider; 0093 class Random; 0094 class CertificateCollection; 0095 class Global; 0096 class KeyStore; 0097 class KeyStoreEntry; 0098 class KeyStoreInfo; 0099 class KeyStoreManager; 0100 class Logger; 0101 0102 /** 0103 Convenience representation for the plugin providers 0104 0105 You can get a list of providers using the providers() 0106 function 0107 0108 \sa ProviderListIterator 0109 \sa providers() 0110 */ 0111 typedef QList<Provider *> ProviderList; 0112 0113 /** 0114 Mode settings for memory allocation 0115 0116 QCA can use secure memory, however most operating systems 0117 restrict the amount of memory that can be pinned by user 0118 applications, to prevent a denial-of-service attack. 0119 0120 QCA supports two approaches to getting memory - the mlock 0121 method, which generally requires root (administrator) level 0122 privileges, and the mmap method which is not as secure, but 0123 which should be able to be used by any process. 0124 0125 \sa Initializer 0126 */ 0127 enum MemoryMode 0128 { 0129 Practical, ///< mlock and drop root if available, else mmap 0130 Locking, ///< mlock and drop root 0131 LockingKeepPrivileges ///< mlock, retaining root privileges 0132 }; 0133 0134 /** 0135 Direction settings for symmetric algorithms 0136 0137 For some algorithms, it makes sense to have a "direction", such 0138 as Cipher algorithms which can be used to encrypt or decrypt. 0139 */ 0140 enum Direction 0141 { 0142 Encode, ///< Operate in the "forward" direction; for example, encrypting 0143 Decode ///< Operate in the "reverse" direction; for example, decrypting 0144 }; 0145 0146 /** 0147 Initialise %QCA. 0148 This call is not normally required, because it is cleaner 0149 to use an Initializer. 0150 */ 0151 QCA_EXPORT void init(); 0152 0153 /** 0154 \overload 0155 0156 \param m the MemoryMode to use 0157 \param prealloc the amount of memory in kilobytes to allocate 0158 for secure storage 0159 */ 0160 QCA_EXPORT void init(MemoryMode m, int prealloc); 0161 0162 /** 0163 Clean up routine 0164 0165 This routine cleans up %QCA, including memory allocations 0166 This call is not normally required, because it is cleaner 0167 to use an Initializer 0168 */ 0169 QCA_EXPORT void deinit(); 0170 0171 /** 0172 Test if secure storage memory is available 0173 0174 \return true if secure storage memory is available 0175 */ 0176 QCA_EXPORT bool haveSecureMemory(); 0177 0178 /** 0179 Test if secure random is available 0180 0181 Secure random is considered available if the global random 0182 provider is not the default provider. 0183 0184 \return true if secure random is available 0185 */ 0186 QCA_EXPORT bool haveSecureRandom(); 0187 0188 /** 0189 Test if a capability (algorithm) is available. 0190 0191 Since capabilities are made available at runtime, you 0192 should always check before using a capability the first 0193 time, as shown below. 0194 \code 0195 QCA::init(); 0196 if(!QCA::isSupported("sha1")) 0197 printf("SHA1 not supported!\n"); 0198 else 0199 { 0200 QString result = QCA::SHA1::hashToString(myString); 0201 printf("sha1(\"%s\") = [%s]\n", myString.data(), qPrintable(result)); 0202 } 0203 \endcode 0204 0205 \param features the name of the capability to test for 0206 \param provider if specified, only check for the capability in that 0207 specific provider. If not provided, or provided as an empty 0208 string, then check for capabilities in all available providers 0209 \return true if the capability is available, otherwise false 0210 0211 Note that you can test for a combination of capabilities, 0212 using a comma delimited list: 0213 \code 0214 QCA::isSupported("sha1,md5"): 0215 \endcode 0216 which will return true if all of the capabilities listed 0217 are present. 0218 */ 0219 QCA_EXPORT bool isSupported(const char *features, const QString &provider = QString()); 0220 0221 /** 0222 \overload 0223 0224 \param features a list of features to test for 0225 \param provider if specified, only check for the capability in that 0226 specific provider. If not provided, or provided as an empty 0227 string, then check for capabilities in all available providers 0228 */ 0229 QCA_EXPORT bool isSupported(const QStringList &features, const QString &provider = QString()); 0230 0231 /** 0232 Generate a list of all the supported features in plugins, 0233 and in built in capabilities 0234 0235 \return a list containing the names of the features 0236 0237 The following code writes a list of features to standard out 0238 \code 0239 QStringList capabilities; 0240 capabilities = QCA::supportedFeatures(); 0241 std::cout << "Supported:" << capabilities.join(",") << std::endl; 0242 \endcode 0243 \sa isSupported(const char *features) 0244 \sa isSupported(const QStringList &features) 0245 \sa defaultFeatures() 0246 */ 0247 QCA_EXPORT QStringList supportedFeatures(); 0248 0249 /** 0250 Generate a list of the built in features. This differs from 0251 supportedFeatures() in that it does not include features provided 0252 by plugins. 0253 0254 \return a list containing the names of the features 0255 0256 The following code writes a list of features to standard out 0257 \code 0258 QStringList capabilities; 0259 capabilities = QCA::defaultFeatures(); 0260 std::cout << "Default:" << capabilities.join(",") << std::endl; 0261 \endcode 0262 0263 \sa isSupported 0264 \sa supportedFeatures() 0265 */ 0266 QCA_EXPORT QStringList defaultFeatures(); 0267 0268 /** 0269 Add a provider to the current list of providers 0270 0271 This function allows you to add a provider to the 0272 current plugin providers at a specified priority. If 0273 a provider with the name already exists, this call fails. 0274 0275 QCA takes ownership of the provider. 0276 0277 \param p a pointer to a Provider object, which must be 0278 set up. 0279 \param priority the priority level to set the provider to 0280 \return true if the provider is added, and false if the 0281 provider is not added (failure) 0282 0283 \sa unloadProvider for unloading specified providers 0284 \sa setProviderPriority for a description of the provider priority system 0285 */ 0286 QCA_EXPORT bool insertProvider(Provider *p, int priority = 0); 0287 0288 /** 0289 Unload specified provider 0290 0291 The specified provider is removed from the list of providers 0292 and deleted. If no provider with the name is found, this call fails. 0293 0294 \param name the name of the provider 0295 \return true if the provider is unloaded, and false if the provider 0296 cannot be found 0297 0298 \sa insertProvider for adding providers 0299 */ 0300 QCA_EXPORT bool unloadProvider(const QString &name); 0301 0302 /** 0303 Change the priority of a specified provider 0304 0305 QCA supports a number of providers, and if a number of providers 0306 support the same algorithm, it needs to choose between them. You 0307 can do this at object instantiation time (by specifying the name 0308 of the provider that should be used). Alternatively, you can provide a 0309 relative priority level at an application level, using this call. 0310 0311 Priority is used at object instantiation time. The provider is selected 0312 according to the following logic: 0313 - if a particular provider is nominated, and that provider supports 0314 the required algorithm, then the nominated provider is used 0315 - if no provider is nominated, or it doesn't support the required 0316 algorithm, then the provider with the lowest priority number will be used, 0317 if that provider supports the algorithm. 0318 - if the provider with the lowest priority number doesn't support 0319 the required algorithm, the provider with the next lowest priority number 0320 will be tried, and so on through to the provider with the largest priority 0321 number 0322 - if none of the plugin providers support the required algorithm, then 0323 the default (built-in) provider will be tried. 0324 0325 \param name the name of the provider 0326 \param priority the new priority of the provider. As a special case, if 0327 you pass in -1, then this provider gets the same priority as the 0328 the last provider that was added or had its priority set using this 0329 call. 0330 0331 \sa providerPriority 0332 */ 0333 QCA_EXPORT void setProviderPriority(const QString &name, int priority); 0334 0335 /** 0336 Return the priority of a specified provider 0337 0338 The name of the provider (eg "qca-ossl") is used to look up the 0339 current priority associated with that provider. If the provider 0340 is not found (or something else went wrong), -1 is returned. 0341 0342 \param name the name of the provider 0343 0344 \return the current priority level 0345 0346 \sa setProviderPriority for a description of the provider priority system 0347 */ 0348 QCA_EXPORT int providerPriority(const QString &name); 0349 0350 /** 0351 Return a list of the current providers 0352 0353 The current plugin providers are provided as a list, which you 0354 can iterate over using ProviderListIterator. 0355 0356 \sa ProviderList 0357 \sa ProviderListIterator 0358 */ 0359 QCA_EXPORT ProviderList providers(); 0360 0361 /** 0362 Return the named provider, or 0 if not found 0363 0364 \param name the name of the provider to search for. 0365 */ 0366 QCA_EXPORT Provider *findProvider(const QString &name); 0367 0368 /** 0369 Return the default provider 0370 */ 0371 QCA_EXPORT Provider *defaultProvider(); 0372 0373 /** 0374 Retrieve plugin paths. It consists of: 0375 1. QCA_PLUGIN_PATH environment if set. 0376 2. \c %QCoreApplication::libraryPaths() . 0377 3. Directory where plugins were installed. 0378 0379 QCA_PLUGIN_PATH is paths list like PATH or QT_PLUGIN_PATH. 0380 It uses system path separator. \";\" on Windows and \":\" on Unix. 0381 0382 This function was introduced in %QCA 2.1. 0383 */ 0384 QCA_EXPORT QStringList pluginPaths(); 0385 0386 /** 0387 Scan for new plugins 0388 */ 0389 QCA_EXPORT void scanForPlugins(); 0390 0391 /** 0392 Unload the current plugins 0393 */ 0394 QCA_EXPORT void unloadAllPlugins(); 0395 0396 /** 0397 Retrieve plugin diagnostic text 0398 */ 0399 QCA_EXPORT QString pluginDiagnosticText(); 0400 0401 /** 0402 Clear plugin diagnostic text 0403 */ 0404 QCA_EXPORT void clearPluginDiagnosticText(); 0405 0406 /** 0407 Add plugin diagnostic text 0408 0409 This function should only be called by providers. 0410 0411 \param text the diagnostic message to append 0412 */ 0413 QCA_EXPORT void appendPluginDiagnosticText(const QString &text); 0414 0415 /** 0416 Set a global property 0417 0418 \param name the name of the property 0419 \param value the value to set the property to 0420 0421 \sa getProperty 0422 */ 0423 QCA_EXPORT void setProperty(const QString &name, const QVariant &value); 0424 0425 /** 0426 Retrieve a global property 0427 0428 \param name the name of the property to look up 0429 0430 \sa setProperty 0431 */ 0432 QCA_EXPORT QVariant getProperty(const QString &name); 0433 0434 /** 0435 Set provider configuration 0436 0437 Allowed value types: QString, int, bool 0438 0439 \param name the name of the provider to set the configuration to 0440 \param config the configuration 0441 */ 0442 QCA_EXPORT void setProviderConfig(const QString &name, const QVariantMap &config); 0443 0444 /** 0445 Retrieve provider configuration 0446 0447 \param name the name of the provider to retrieve the configuration of 0448 */ 0449 QCA_EXPORT QVariantMap getProviderConfig(const QString &name); 0450 0451 /** 0452 Save provider configuration to persistent storage 0453 0454 \param name the name of the provider to have its configuration saved 0455 */ 0456 QCA_EXPORT void saveProviderConfig(const QString &name); 0457 0458 /** 0459 Return the name of the global random number provider 0460 */ 0461 QCA_EXPORT QString globalRandomProvider(); 0462 0463 /** 0464 Change the global random number provider 0465 0466 The Random capabilities of %QCA are provided as part of the 0467 built in capabilities, however the generator can be changed 0468 if required. 0469 0470 \param provider the name of the provider to use as the global random 0471 provider. 0472 */ 0473 QCA_EXPORT void setGlobalRandomProvider(const QString &provider); 0474 0475 /** 0476 Return a reference to the %QCA Logger, which is used for diagnostics 0477 and error recording. 0478 0479 The system Logger is automatically created for you on start. 0480 */ 0481 QCA_EXPORT Logger *logger(); 0482 0483 /** 0484 Log a text message. This is an efficient function 0485 to avoid overhead of argument executions when log level 0486 blocks the message. 0487 0488 \param message the text to log 0489 \param severity the type of information to log 0490 0491 \note This is a macro, so arguments may or may not be evaluated. 0492 */ 0493 #define QCA_logTextMessage(message, severity) \ 0494 do { \ 0495 QCA::Logger::Severity s = severity; \ 0496 QCA::Logger *l = QCA::logger(); \ 0497 if (s <= l->level()) { \ 0498 l->logTextMessage(message, s); \ 0499 } \ 0500 } while (false) 0501 0502 /** 0503 Log a binary message. This is an efficient function 0504 to avoid overhead of argument executions when log level 0505 blocks the message. 0506 0507 \param blob the blob to log 0508 \param severity the type of information to log 0509 0510 \note This is a macro, so arguments may or may not be evaluated. 0511 */ 0512 #define QCA_logBinaryMessage(blob, severity) \ 0513 do { \ 0514 QCA::Logger::Severity s = severity; \ 0515 QCA::Logger *l = QCA::logger(); \ 0516 if (s <= l->level()) { \ 0517 l->logBinaryMessage(blob, s); \ 0518 } \ 0519 } while (false) 0520 0521 /** 0522 Test if QCA can access the root CA certificates 0523 0524 If root certificates are available, this function returns true, 0525 otherwise it returns false. 0526 0527 \sa systemStore 0528 */ 0529 QCA_EXPORT bool haveSystemStore(); 0530 0531 /** 0532 Get system-wide root Certificate Authority (CA) certificates 0533 0534 Many operating systems (or distributions, on Linux-type systems) 0535 come with some trusted certificates. Typically, these include 0536 the root certificates for major Certificate Authorities (for 0537 example, Verisign, Comodo) and some additional certificates that 0538 are used for system updates. They are provided in different ways 0539 for different systems. 0540 0541 This function provides an common way to access the system 0542 certificates. There are other ways to access certificates - see 0543 the various I/O methods (such as fromDER() and fromPEM()) 0544 in the Certificate and CertificateCollection classes. 0545 0546 \note Availability of the system certificates depends on how 0547 %QCA was built. You can test whether the system certificates 0548 are available using the haveSystemStore() function. 0549 0550 */ 0551 QCA_EXPORT CertificateCollection systemStore(); 0552 0553 /** 0554 Get the application name that will be used by SASL server mode 0555 0556 The application name is used by SASL in server mode, as some systems might 0557 have different security policies depending on the app. 0558 The default application name is 'qca' 0559 */ 0560 QCA_EXPORT QString appName(); 0561 0562 /** 0563 Set the application name that will be used by SASL server mode 0564 0565 The application name is used by SASL in server mode, as some systems might 0566 have different security policies depending on the app. This should be set 0567 before using SASL objects, and it cannot be changed later. 0568 0569 \param name the name string to use for SASL server mode 0570 */ 0571 QCA_EXPORT void setAppName(const QString &name); 0572 0573 /** 0574 Convert a byte array to printable hexadecimal 0575 representation. 0576 0577 This is a convenience function to convert an arbitrary 0578 QByteArray to a printable representation. 0579 0580 \code 0581 QByteArray test(10); 0582 test.fill('a'); 0583 // 0x61 is 'a' in ASCII 0584 if (QString("61616161616161616161") == QCA::arrayToHex(test) ) 0585 { 0586 printf ("arrayToHex passed\n"); 0587 } 0588 \endcode 0589 0590 \param array the array to be converted 0591 \return a printable representation 0592 */ 0593 QCA_EXPORT QString arrayToHex(const QByteArray &array); 0594 0595 /** 0596 Convert a QString containing a hexadecimal representation 0597 of a byte array into a QByteArray 0598 0599 This is a convenience function to convert a printable 0600 representation into a QByteArray - effectively the inverse 0601 of QCA::arrayToHex. 0602 0603 \code 0604 QCA::init(); 0605 QByteArray test(10); 0606 0607 test.fill('b'); // 0x62 in hexadecimal 0608 test[7] = 0x00; // can handle strings with nulls 0609 0610 if (QCA::hexToArray(QString("62626262626262006262") ) == test ) 0611 { 0612 printf ("hexToArray passed\n"); 0613 } 0614 \endcode 0615 0616 \param hexString the string containing a printable 0617 representation to be converted 0618 \return the equivalent QByteArray 0619 */ 0620 QCA_EXPORT QByteArray hexToArray(const QString &hexString); 0621 0622 /** 0623 Convert a byte array to printable base64 0624 representation. 0625 0626 This is a convenience function to convert an arbitrary 0627 QByteArray to a printable representation. 0628 0629 \param array the array to be converted 0630 \return a printable representation 0631 */ 0632 QCA_EXPORT QString arrayToBase64(const QByteArray &array); 0633 0634 /** 0635 Convert a QString containing a base64 representation 0636 of a byte array into a QByteArray 0637 0638 This is a convenience function to convert a printable 0639 representation into a QByteArray - effectively the inverse 0640 of QCA::arrayToBase64. 0641 0642 \param base64String the string containing a printable 0643 representation to be converted 0644 \return the equivalent QByteArray 0645 */ 0646 QCA_EXPORT QByteArray base64ToArray(const QString &base64String); 0647 0648 /** 0649 \class Initializer qca_core.h QtCrypto 0650 0651 Convenience method for initialising and cleaning up %QCA 0652 0653 To ensure that QCA is properly initialised and cleaned up, 0654 it is convenient to create an Initializer object, and let it 0655 go out of scope at the end of %QCA usage. 0656 0657 \ingroup UserAPI 0658 */ 0659 class QCA_EXPORT Initializer 0660 { 0661 public: 0662 /** 0663 Standard constructor 0664 0665 \param m the MemoryMode to use for secure memory 0666 \param prealloc the amount of secure memory to pre-allocate, 0667 in units of 1024 bytes (1K). 0668 */ 0669 explicit Initializer(MemoryMode m = Practical, int prealloc = 64); 0670 ~Initializer(); 0671 0672 Initializer(const Initializer &) = delete; 0673 Initializer &operator=(const Initializer &) = delete; 0674 }; 0675 0676 /** 0677 \class KeyLength qca_core.h QtCrypto 0678 0679 Simple container for acceptable key lengths 0680 0681 The KeyLength specifies the minimum and maximum byte sizes 0682 allowed for a key, as well as a "multiple" which the key 0683 size must evenly divide into. 0684 0685 As an example, if the key can be 4, 8 or 12 bytes, you can 0686 express this as 0687 \code 0688 KeyLength keyLen( 4, 12, 4 ); 0689 \endcode 0690 0691 If you want to express a KeyLength that takes any number 0692 of bytes (including zero), you may want to use 0693 \code 0694 #include<limits> 0695 KeyLength( 0, std::numeric_limits<int>::max(), 1 ); 0696 \endcode 0697 0698 \ingroup UserAPI 0699 */ 0700 class QCA_EXPORT KeyLength 0701 { 0702 public: 0703 /** 0704 Construct a %KeyLength object 0705 0706 \param min the minimum length of the key, in bytes 0707 \param max the maximum length of the key, in bytes 0708 \param multiple the number of bytes that the key must be a 0709 multiple of. 0710 */ 0711 KeyLength(int min, int max, int multiple) 0712 : _min(min) 0713 , _max(max) 0714 , _multiple(multiple) 0715 { 0716 } 0717 0718 /** 0719 Obtain the minimum length for the key, in bytes 0720 */ 0721 int minimum() const 0722 { 0723 return _min; 0724 } 0725 0726 /** 0727 Obtain the maximum length for the key, in bytes 0728 */ 0729 int maximum() const 0730 { 0731 return _max; 0732 } 0733 0734 /** 0735 Return the number of bytes that the key must be a multiple of 0736 0737 If this is one, then anything between minimum and maximum (inclusive) 0738 is acceptable. 0739 */ 0740 int multiple() const 0741 { 0742 return _multiple; 0743 } 0744 0745 private: 0746 const int _min, _max, _multiple; 0747 }; 0748 0749 /** 0750 \class Provider qca_core.h QtCrypto 0751 0752 Algorithm provider 0753 0754 Provider represents a plugin provider (or as a special case, the 0755 built-in provider). This is the class you need to inherit 0756 from to create your own plugin. You don't normally need to 0757 worry about this class if you are just using existing 0758 QCA capabilities and plugins, however there is nothing stopping 0759 you from using it to obtain information about specific plugins, 0760 as shown in the example below. 0761 0762 \ingroup ProviderAPI 0763 */ 0764 class QCA_EXPORT Provider 0765 { 0766 public: 0767 virtual ~Provider(); 0768 0769 class Context; 0770 0771 /** 0772 Initialisation routine 0773 0774 This routine will be called when your plugin 0775 is loaded, so this is a good place to do any 0776 one-off initialisation tasks. If you don't need 0777 any initialisation, just implement it as an empty 0778 routine. 0779 */ 0780 virtual void init(); 0781 0782 /** 0783 Deinitialisation routine 0784 0785 This routine will be called just before provider destruction. 0786 Notably, during QCA shutdown, deinit() will be called on all 0787 providers before any of the providers are destructed. Use this 0788 opportunity to free any resources that may be used by other 0789 providers. 0790 */ 0791 virtual void deinit(); 0792 0793 /** 0794 Version number of the plugin 0795 0796 The format is the same as QCA itself. Version 1.2.3 would be 0797 represented as 0x010203. 0798 0799 The default returns 0 (version 0.0.0). 0800 */ 0801 virtual int version() const; 0802 0803 /** 0804 Target QCA version for the provider. 0805 0806 This is used to verify compatibility between the 0807 provider and QCA. For a provider to be used, it 0808 must supply major and minor version numbers here that are 0809 less-than or equal to the actual QCA version (the patch 0810 version number is ignored). This means an older 0811 provider may be used with a newer QCA, but a newer 0812 provider cannot be used with an older QCA. 0813 */ 0814 virtual int qcaVersion() const = 0; 0815 0816 /** 0817 The name of the provider. 0818 0819 Typically you just return a string containing a 0820 convenient name. 0821 0822 \code 0823 QString name() const 0824 { 0825 return "qca-myplugin"; 0826 } 0827 \endcode 0828 0829 \note The name is used to tell if a provider is 0830 already loaded, so you need to make sure it is 0831 unique amongst the various plugins. 0832 */ 0833 virtual QString name() const = 0; 0834 0835 /** 0836 The capabilities (algorithms) of the provider. 0837 0838 Typically you just return a fixed QStringList: 0839 \code 0840 QStringList features() const 0841 { 0842 QStringList list; 0843 list += "sha1"; 0844 list += "sha256"; 0845 list += "hmac(sha1)"; 0846 return list; 0847 } 0848 \endcode 0849 */ 0850 virtual QStringList features() const = 0; 0851 0852 /** 0853 Optional credit text for the provider. 0854 0855 You might display this information in a credits or 0856 "About" dialog. Returns an empty string if the 0857 provider has no credit text. Only report credit text 0858 when absolutely required (for example, an "advertisement 0859 clause" related to licensing). Do not use it for 0860 reporting general author information. 0861 */ 0862 virtual QString credit() const; 0863 0864 /** 0865 Routine to create a plugin context 0866 0867 You need to return a pointer to an algorithm 0868 Context that corresponds with the algorithm 0869 name specified. 0870 0871 \param type the name of the algorithm required 0872 0873 \code 0874 Context *createContext(const QString &type) 0875 { 0876 if ( type == "sha1" ) 0877 return new SHA1Context( this ); 0878 else if ( type == "sha256" ) 0879 return new SHA0256Context( this ); 0880 else if ( type == "hmac(sha1)" ) 0881 return new HMACSHA1Context( this ); 0882 else 0883 return 0; 0884 } 0885 \endcode 0886 0887 Naturally you also need to implement 0888 the specified Context subclasses as well. 0889 */ 0890 virtual Context *createContext(const QString &type) = 0; 0891 0892 /** 0893 Method to set up the default configuration options. 0894 0895 If your provider needs some configuration options, 0896 this method allows you to establish default options. 0897 The user can then change the configuration options 0898 as required, and set them using configChanged(). 0899 0900 You need to return a QVariantMap that has configuration 0901 options as the keys, and the default configuration 0902 as the values, as shown below: 0903 \code 0904 QVariantMap defaultConfig() const 0905 { 0906 QVariantMap myConfig; 0907 myConfig[ "firstOption" ] = QString("firstOptionValue"); 0908 myConfig[ "secondOption" ] = true; 0909 myConfig[ "thirdOpt" ] = 1243; 0910 return myConfig; 0911 } 0912 \endcode 0913 0914 \sa configChanged for how to set the configuration; 0915 */ 0916 virtual QVariantMap defaultConfig() const; 0917 0918 /** 0919 Method to set the configuration options. 0920 0921 If your provider supports configuration options, you 0922 will be advised of user changes to the configuration 0923 when this method is called. 0924 0925 \param config the new configuration to be used by the provider 0926 */ 0927 virtual void configChanged(const QVariantMap &config); 0928 }; 0929 0930 /** 0931 \class QCA::Provider::Context qca_core.h QtCrypto 0932 0933 Internal context class used for the plugin 0934 0935 \internal 0936 0937 \ingroup ProviderAPI 0938 */ 0939 class QCA_EXPORT Provider::Context : public QObject 0940 { 0941 Q_OBJECT 0942 public: 0943 ~Context() override; 0944 0945 /** 0946 The Provider associated with this Context 0947 */ 0948 Provider *provider() const; 0949 0950 /** 0951 The type of context, as passed to the constructor 0952 */ 0953 QString type() const; 0954 0955 /** 0956 Create a duplicate of this Context 0957 */ 0958 virtual Context *clone() const = 0; 0959 0960 /** 0961 Test if two Contexts have the same Provider 0962 0963 \param c pointer to the Context to compare to 0964 0965 \return true if the argument and this Context 0966 have the same provider. 0967 */ 0968 bool sameProvider(const Context *c) const; 0969 0970 protected: 0971 /** 0972 Standard constructor 0973 0974 \param parent the parent provider for this 0975 context 0976 \param type the name of the provider context type 0977 */ 0978 Context(Provider *parent, const QString &type); 0979 0980 /** 0981 Copy constructor 0982 0983 \param from the Context to copy from 0984 */ 0985 Context(const Context &from); 0986 0987 private: 0988 // disable assignment 0989 Context &operator=(const Context &from); 0990 0991 Provider *_provider; 0992 QString _type; 0993 }; 0994 0995 /** 0996 \class BasicContext qca_core.h QtCrypto 0997 0998 Base class to use for primitive provider contexts 0999 1000 \internal 1001 1002 This class inherits Provider::Context and calls moveToThread(0) on 1003 itself, thereby disabling the event properties of the underlying 1004 QObject. Context types that need to be a QObject should inherit from 1005 Provider::Context, those that don't should inherit from BasicContext. 1006 1007 \ingroup ProviderAPI 1008 */ 1009 class QCA_EXPORT BasicContext : public Provider::Context 1010 { 1011 Q_OBJECT 1012 public: 1013 ~BasicContext() override; 1014 1015 protected: 1016 /** 1017 Standard constructor 1018 1019 \param parent the parent provider for this 1020 context 1021 \param type the name of the provider context type 1022 */ 1023 BasicContext(Provider *parent, const QString &type); 1024 1025 /** 1026 Copy constructor 1027 1028 \param from the Context to copy from 1029 */ 1030 BasicContext(const BasicContext &from); 1031 1032 private: 1033 // disable assignment 1034 BasicContext &operator=(const BasicContext &from); 1035 }; 1036 1037 /** 1038 \class BufferedComputation qca_core.h QtCrypto 1039 1040 General superclass for buffered computation algorithms 1041 1042 A buffered computation is characterised by having the 1043 algorithm take data in an incremental way, then having 1044 the results delivered at the end. Conceptually, the 1045 algorithm has some internal state that is modified 1046 when you call update() and returned when you call 1047 final(). 1048 1049 \ingroup UserAPI 1050 */ 1051 class QCA_EXPORT BufferedComputation 1052 { 1053 public: 1054 virtual ~BufferedComputation(); 1055 1056 /** 1057 Reset the internal state 1058 */ 1059 virtual void clear() = 0; 1060 1061 /** 1062 Update the internal state with a byte array 1063 1064 \param a the byte array of data that is to 1065 be used to update the internal state. 1066 */ 1067 virtual void update(const MemoryRegion &a) = 0; 1068 1069 /** 1070 Complete the algorithm and return the internal state 1071 */ 1072 virtual MemoryRegion final() = 0; 1073 1074 /** 1075 Perform an "all in one" update, returning 1076 the result. This is appropriate if you 1077 have all the data in one array - just 1078 call process on that array, and you will 1079 get back the results of the computation. 1080 1081 \note This will invalidate any previous 1082 computation using this object. 1083 1084 \param a the data to process. 1085 */ 1086 MemoryRegion process(const MemoryRegion &a); 1087 }; 1088 1089 /** 1090 \class Filter qca_core.h QtCrypto 1091 1092 General superclass for filtering transformation algorithms 1093 1094 A filtering computation is characterised by having the 1095 algorithm take input data in an incremental way, with results 1096 delivered for each input, or block of input. Some internal 1097 state may be managed, with the transformation completed 1098 when final() is called. 1099 1100 If this seems a big vague, then you might try deriving 1101 your class from a subclass with stronger semantics, or if your 1102 update() function is always returning null results, and 1103 everything comes out at final(), try BufferedComputation. 1104 1105 \ingroup UserAPI 1106 */ 1107 class QCA_EXPORT Filter 1108 { 1109 public: 1110 virtual ~Filter(); 1111 1112 /** 1113 Reset the internal state 1114 */ 1115 virtual void clear() = 0; 1116 1117 /** 1118 Process more data, returning the corresponding 1119 filtered version of the data. 1120 1121 \param a the array containing data to process 1122 */ 1123 virtual MemoryRegion update(const MemoryRegion &a) = 0; 1124 1125 /** 1126 Complete the algorithm, returning any 1127 additional results. 1128 */ 1129 virtual MemoryRegion final() = 0; 1130 1131 /** 1132 Test if an update() or final() call succeeded. 1133 1134 \return true if the previous call succeeded 1135 */ 1136 virtual bool ok() const = 0; 1137 1138 /** 1139 Perform an "all in one" update, returning 1140 the result. This is appropriate if you 1141 have all the data in one array - just 1142 call process on that array, and you will 1143 get back the results of the computation. 1144 1145 \note This will invalidate any previous 1146 computation using this object. 1147 1148 \param a the data to process in this step 1149 */ 1150 MemoryRegion process(const MemoryRegion &a); 1151 }; 1152 1153 /** 1154 \class Algorithm qca_core.h QtCrypto 1155 1156 General superclass for an algorithm. 1157 1158 This is a fairly abstract class, mainly used for 1159 implementing the backend "provider" interface. 1160 1161 \ingroup UserAPI 1162 */ 1163 class QCA_EXPORT Algorithm 1164 { 1165 public: 1166 /** 1167 Standard copy constructor 1168 1169 \param from the Algorithm to copy from 1170 */ 1171 Algorithm(const Algorithm &from); 1172 1173 virtual ~Algorithm(); 1174 1175 /** 1176 Assignment operator 1177 1178 \param from the Algorithm to copy state from 1179 */ 1180 Algorithm &operator=(const Algorithm &from); 1181 1182 /** 1183 The name of the algorithm type. 1184 */ 1185 QString type() const; 1186 1187 /** 1188 The name of the provider 1189 1190 Each algorithm is implemented by a provider. This 1191 allows you to figure out which provider is associated 1192 */ 1193 Provider *provider() const; 1194 1195 // Note: The next five functions are not public! 1196 1197 /** 1198 \internal 1199 1200 The context associated with this algorithm 1201 */ 1202 Provider::Context *context(); 1203 1204 /** 1205 \internal 1206 1207 The context associated with this algorithm 1208 */ 1209 const Provider::Context *context() const; 1210 1211 /** 1212 \internal 1213 1214 Set the Provider for this algorithm 1215 1216 \param c the context for the Provider to use 1217 */ 1218 void change(Provider::Context *c); 1219 1220 /** 1221 \internal 1222 1223 \overload 1224 1225 \param type the name of the algorithm to use 1226 \param provider the name of the preferred provider 1227 */ 1228 void change(const QString &type, const QString &provider); 1229 1230 /** 1231 \internal 1232 1233 Take the Provider from this algorithm 1234 */ 1235 Provider::Context *takeContext(); 1236 1237 protected: 1238 /** 1239 Constructor for empty algorithm 1240 */ 1241 Algorithm(); 1242 1243 /** 1244 Constructor of a particular algorithm. 1245 1246 \param type the algorithm to construct 1247 \param provider the name of a particular Provider 1248 */ 1249 Algorithm(const QString &type, const QString &provider); 1250 1251 private: 1252 class Private; 1253 QSharedDataPointer<Private> d; 1254 }; 1255 1256 /** 1257 \class SymmetricKey qca_core.h QtCrypto 1258 1259 Container for keys for symmetric encryption algorithms. 1260 1261 \ingroup UserAPI 1262 */ 1263 class QCA_EXPORT SymmetricKey : public SecureArray 1264 { 1265 public: 1266 /** 1267 Construct an empty (zero length) key 1268 */ 1269 SymmetricKey(); 1270 1271 /** 1272 Construct an key of specified size, with random contents 1273 1274 This is intended to be used as a random session key. 1275 1276 \param size the number of bytes for the key 1277 */ 1278 SymmetricKey(int size); 1279 1280 /** 1281 Construct a key from a provided byte array 1282 1283 \param a the byte array to copy 1284 */ 1285 SymmetricKey(const SecureArray &a); 1286 1287 /** 1288 Construct a key from a provided byte array 1289 1290 \param a the byte array to copy 1291 */ 1292 SymmetricKey(const QByteArray &a); 1293 1294 /** 1295 Test for weak DES keys 1296 1297 \return true if the key is a weak key for DES 1298 */ 1299 bool isWeakDESKey(); 1300 }; 1301 1302 /** 1303 \class InitializationVector qca_core.h QtCrypto 1304 1305 Container for initialisation vectors and nonces 1306 1307 \ingroup UserAPI 1308 */ 1309 class QCA_EXPORT InitializationVector : public SecureArray 1310 { 1311 public: 1312 /** 1313 Construct an empty (zero length) initialization vector 1314 */ 1315 InitializationVector(); 1316 1317 /** 1318 Construct an initialization vector of the specified size 1319 1320 \param size the length of the initialization vector, in bytes 1321 */ 1322 InitializationVector(int size); 1323 1324 /** 1325 Construct an initialization vector from a provided byte array 1326 1327 \param a the byte array to copy 1328 */ 1329 InitializationVector(const SecureArray &a); 1330 1331 /** 1332 Construct an initialization vector from a provided byte array 1333 1334 \param a the byte array to copy 1335 */ 1336 InitializationVector(const QByteArray &a); 1337 }; 1338 1339 /** 1340 \class AuthTag qca_core.h QtCrypto 1341 1342 Container for authentication tag 1343 1344 \ingroup UserAPI 1345 */ 1346 class QCA_EXPORT AuthTag : public SecureArray 1347 { 1348 public: 1349 /** 1350 Construct an empty authentication tag 1351 */ 1352 AuthTag(); 1353 1354 /** 1355 Construct an empty authentication tag of the specified size 1356 1357 \param size the length of the authentication tag, in bytes 1358 */ 1359 AuthTag(int size); 1360 1361 /** 1362 Construct an authentication tag from a provided byte array 1363 1364 \param a the byte array to copy 1365 */ 1366 AuthTag(const SecureArray &a); 1367 1368 /** 1369 Construct an authentication tag from a provided byte array 1370 1371 \param a the byte array to copy 1372 */ 1373 AuthTag(const QByteArray &a); 1374 }; 1375 1376 /** 1377 \class Event qca_core.h QtCrypto 1378 1379 An asynchronous event 1380 1381 Events are produced in response to the library's need for some user 1382 intervention, such as entering a pin or password, or inserting a 1383 cryptographic token. 1384 1385 Event is an abstraction, so you can handle this need in a way that makes 1386 sense for your application. 1387 1388 \ingroup UserAPI 1389 */ 1390 class QCA_EXPORT Event 1391 { 1392 public: 1393 /** 1394 %Type of event 1395 1396 \sa type() 1397 */ 1398 enum Type 1399 { 1400 Password, ///< Asking for a password, PIN or passphrase. 1401 Token ///< Asking for a token 1402 }; 1403 1404 /** 1405 %Source of the event 1406 1407 Events are associated with access to a KeyStore, or access to 1408 a file (or bytearray/stream or equivalent). This tells you the 1409 type of source that caused the Event. 1410 1411 \sa source() 1412 \sa fileName() for the name, if source is Event::Data 1413 \sa keyStoreInfo() and keyStoreEntry() for the keystore and entry, 1414 if the source is Event::KeyStore 1415 */ 1416 enum Source 1417 { 1418 KeyStore, ///< KeyStore generated the event 1419 Data ///< File or bytearray generated the event 1420 }; 1421 1422 /** 1423 password variation 1424 1425 If the Type of Event is Password, PasswordStyle tells you whether 1426 it is a PIN, passphrase or password. 1427 1428 \sa passwordStyle() 1429 */ 1430 enum PasswordStyle 1431 { 1432 StylePassword, ///< User should be prompted for a "Password" 1433 StylePassphrase, ///< User should be prompted for a "Passphrase" 1434 StylePIN ///< User should be prompted for a "PIN" 1435 }; 1436 1437 /** 1438 Constructor 1439 */ 1440 Event(); 1441 1442 /** 1443 Copy constructor 1444 1445 \param from the Event to copy from 1446 */ 1447 Event(const Event &from); 1448 1449 /** 1450 Destructor 1451 */ 1452 ~Event(); 1453 1454 /** 1455 Assignment operator 1456 1457 \param from the Event to copy from 1458 */ 1459 Event &operator=(const Event &from); 1460 1461 /** 1462 test if this event has been setup correctly 1463 */ 1464 bool isNull() const; 1465 1466 /** 1467 the Type of this event 1468 */ 1469 Type type() const; 1470 1471 /** 1472 the Source of this event 1473 */ 1474 Source source() const; 1475 1476 /** 1477 the style of password required. 1478 1479 This is not meaningful unless the Type is Event::Password. 1480 1481 \sa PasswordStyle 1482 */ 1483 PasswordStyle passwordStyle() const; 1484 1485 /** 1486 The info of the KeyStore associated with this event 1487 1488 This is not meaningful unless the Source is KeyStore. 1489 */ 1490 KeyStoreInfo keyStoreInfo() const; 1491 1492 /** 1493 The KeyStoreEntry associated with this event 1494 1495 This is not meaningful unless the Source is KeyStore. 1496 */ 1497 KeyStoreEntry keyStoreEntry() const; 1498 1499 /** 1500 Name or other identifier for the file or byte array 1501 associated with this event. 1502 1503 This is not meaningful unless the Source is Data. 1504 */ 1505 QString fileName() const; 1506 1507 /** 1508 opaque data 1509 */ 1510 void *ptr() const; 1511 1512 /** 1513 Set the values for this Event 1514 1515 This creates a Password type event, for a keystore. 1516 1517 \param pstyle the style of information required (e.g. PIN, 1518 password or passphrase) 1519 \param keyStoreInfo info about the keystore that the information 1520 is required for 1521 \param keyStoreEntry the entry in the keystore that the 1522 information is required for 1523 \param ptr opaque data 1524 */ 1525 void setPasswordKeyStore(PasswordStyle pstyle, 1526 const KeyStoreInfo &keyStoreInfo, 1527 const KeyStoreEntry &keyStoreEntry, 1528 void *ptr); 1529 1530 /** 1531 Set the values for this Event 1532 1533 This creates a Password type event, for a file. 1534 1535 \param pstyle the style of information required (e.g. PIN, 1536 password or passphrase) 1537 \param fileName the name of the file (or other identifier) that 1538 the information is required for 1539 \param ptr opaque data 1540 */ 1541 void setPasswordData(PasswordStyle pstyle, const QString &fileName, void *ptr); 1542 1543 /** 1544 Set the values for this Event 1545 1546 This creates a Token type event. 1547 1548 \param keyStoreInfo info about the keystore that the token is 1549 required for 1550 \param keyStoreEntry the entry in the keystore that the token is 1551 required for 1552 \param ptr opaque data 1553 */ 1554 void setToken(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr); 1555 1556 private: 1557 class Private; 1558 QSharedDataPointer<Private> d; 1559 }; 1560 1561 /** 1562 \class EventHandler qca_core.h QtCrypto 1563 1564 Interface class for password / passphrase / PIN and token handlers 1565 1566 This class is used on client side applications to handle 1567 the provision of passwords, passphrases and PINs by users, and 1568 to indicate that tokens have been correctly inserted. 1569 1570 The concept behind this class is that the library can raise 1571 events (typically using PasswordAsker or TokenAsker), which 1572 may (or may not) be handled by the application using a 1573 handler object (that has-a EventHandler, or possibly is-a 1574 EventHandler) that is connected to the eventReady() signal. 1575 1576 \ingroup UserAPI 1577 */ 1578 class QCA_EXPORT EventHandler : public QObject 1579 { 1580 Q_OBJECT 1581 public: 1582 /** 1583 Constructor 1584 1585 \param parent the parent object for this object 1586 */ 1587 EventHandler(QObject *parent = nullptr); 1588 ~EventHandler() override; 1589 1590 /** 1591 mandatory function to call after connecting the 1592 signal to a slot in your application specific password 1593 / passphrase / PIN or token handler 1594 */ 1595 void start(); 1596 1597 /** 1598 function to call to return the user provided 1599 password, passphrase or PIN. 1600 1601 \param id the id corresponding to the password request 1602 \param password the user-provided password, passphrase or PIN. 1603 1604 \note the id parameter is the same as that provided in the 1605 eventReady() signal. 1606 */ 1607 void submitPassword(int id, const SecureArray &password); 1608 1609 /** 1610 function to call to indicate that the token has been inserted 1611 by the user. 1612 1613 \param id the id corresponding to the password request 1614 1615 \note the id parameter is the same as that provided in the 1616 eventReady() signal. 1617 */ 1618 void tokenOkay(int id); 1619 1620 /** 1621 function to call to indicate that the user declined to 1622 provide a password, passphrase, PIN or token. 1623 1624 \param id the id corresponding to the password request 1625 1626 \note the id parameter is the same as that provided in the 1627 eventReady() signal. 1628 */ 1629 void reject(int id); 1630 1631 Q_SIGNALS: 1632 /** 1633 signal emitted when an Event requires attention. 1634 1635 You typically need to connect this signal to 1636 a compatible slot in your callback handler 1637 1638 \param id the identification number for the event 1639 \param context information about the type of response required 1640 */ 1641 void eventReady(int id, const QCA::Event &context); 1642 1643 private: 1644 Q_DISABLE_COPY(EventHandler) 1645 1646 class Private; 1647 friend class Private; 1648 Private *d; 1649 }; 1650 1651 /** 1652 \class PasswordAsker qca_core.h QtCrypto 1653 1654 User password / passphrase / PIN handler 1655 1656 This class is used to obtain a password from a user. 1657 1658 \ingroup UserAPI 1659 */ 1660 class QCA_EXPORT PasswordAsker : public QObject 1661 { 1662 Q_OBJECT 1663 public: 1664 /** 1665 Construct a new asker 1666 1667 \param parent the parent object for this QObject 1668 */ 1669 PasswordAsker(QObject *parent = nullptr); 1670 ~PasswordAsker() override; 1671 1672 /** 1673 queue a password / passphrase request associated with a key store 1674 1675 \param pstyle the type of information required (e.g. PIN, 1676 passphrase or password) 1677 \param keyStoreInfo info of the key store that the information is 1678 required for 1679 \param keyStoreEntry the item in the key store that the 1680 information is required for (if applicable) 1681 \param ptr opaque data 1682 */ 1683 void 1684 ask(Event::PasswordStyle pstyle, const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr); 1685 1686 /** 1687 queue a password / passphrase request associated with a file 1688 1689 \param pstyle the type of information required (e.g. PIN, 1690 passphrase or password) 1691 \param fileName the name of the file that the information is 1692 required for 1693 \param ptr opaque data 1694 */ 1695 void ask(Event::PasswordStyle pstyle, const QString &fileName, void *ptr); 1696 1697 /** 1698 Cancel the pending password / passphrase request 1699 */ 1700 void cancel(); 1701 1702 /** 1703 Block until the password / passphrase request is 1704 completed 1705 1706 You can use the responseReady signal instead of 1707 blocking, if appropriate. 1708 */ 1709 void waitForResponse(); 1710 1711 /** 1712 Determine whether the password / passphrase was accepted or not 1713 1714 In this context, returning true is indicative of the user clicking 1715 "Ok" or equivalent; and returning false indicates that either the 1716 user clicked "Cancel" or equivalent, or that the cancel() function 1717 was called, or that the request is still pending. 1718 */ 1719 bool accepted() const; 1720 1721 /** 1722 The password / passphrase / PIN provided by the user in response 1723 to the asker request. This may be empty. 1724 */ 1725 SecureArray password() const; 1726 1727 Q_SIGNALS: 1728 /** 1729 Emitted when the asker process has been completed. 1730 1731 You should check whether the user accepted() the response 1732 prior to relying on the password(). 1733 */ 1734 void responseReady(); 1735 1736 private: 1737 Q_DISABLE_COPY(PasswordAsker) 1738 1739 class Private; 1740 friend class Private; 1741 Private *d; 1742 }; 1743 1744 /** 1745 \class TokenAsker qca_core.h QtCrypto 1746 1747 User token handler 1748 1749 This class is used to request the user to insert a token. 1750 1751 \ingroup UserAPI 1752 */ 1753 class QCA_EXPORT TokenAsker : public QObject 1754 { 1755 Q_OBJECT 1756 public: 1757 /** 1758 Construct a new asker 1759 1760 \param parent the parent object for this QObject 1761 */ 1762 TokenAsker(QObject *parent = nullptr); 1763 ~TokenAsker() override; 1764 1765 /** 1766 queue a token request associated with a key store 1767 1768 \param keyStoreInfo info of the key store that the information is 1769 required for 1770 \param keyStoreEntry the item in the key store that the 1771 information is required for (if applicable) 1772 \param ptr opaque data 1773 */ 1774 void ask(const KeyStoreInfo &keyStoreInfo, const KeyStoreEntry &keyStoreEntry, void *ptr); 1775 1776 /** 1777 Cancel the pending password / passphrase request 1778 */ 1779 void cancel(); 1780 1781 /** 1782 Block until the token request is completed 1783 1784 You can use the responseReady signal instead of 1785 blocking, if appropriate. 1786 */ 1787 void waitForResponse(); 1788 1789 /** 1790 Test if the token request was accepted or not. 1791 1792 \return true if the token request was accepted 1793 */ 1794 bool accepted() const; 1795 1796 Q_SIGNALS: 1797 /** 1798 Emitted when the asker process has been completed. 1799 1800 You should check whether the user accepted() the response 1801 prior to relying on token being present. 1802 */ 1803 void responseReady(); 1804 1805 private: 1806 Q_DISABLE_COPY(TokenAsker) 1807 1808 class Private; 1809 friend class Private; 1810 Private *d; 1811 }; 1812 1813 } 1814 1815 #endif