File indexing completed on 2024-04-28 04:43:41
0001 /* 0002 * qca_publickey.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 * 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 qca_publickey.h 0025 0026 Header file for PublicKey and PrivateKey related classes 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 QCA_PUBLICKEY_H 0034 #define QCA_PUBLICKEY_H 0035 0036 #include "qca_core.h" 0037 #include <QObject> 0038 0039 namespace QCA { 0040 0041 class PublicKey; 0042 class PrivateKey; 0043 class KeyGenerator; 0044 class RSAPublicKey; 0045 class RSAPrivateKey; 0046 class DSAPublicKey; 0047 class DSAPrivateKey; 0048 class DHPublicKey; 0049 class DHPrivateKey; 0050 0051 /** 0052 Encryption algorithms 0053 */ 0054 enum EncryptionAlgorithm 0055 { 0056 EME_PKCS1v15, ///< Block type 2 (PKCS#1, Version 1.5) 0057 EME_PKCS1_OAEP, ///< Optimal asymmetric encryption padding (PKCS#1, Version 2.0) 0058 EME_PKCS1v15_SSL, ///< PKCS#1, Version 1.5 with an SSL-specific modification 0059 EME_NO_PADDING ///< Raw RSA encryption 0060 }; 0061 0062 /** 0063 Signature algorithm variants 0064 0065 Note that most signature algorithms follow a process of first hashing the 0066 plaintext data to be signed, creating a payload format that wraps the hash 0067 value (among other things), and then signing the payload with the private 0068 key. So, for example, an EMSA3(SHA1) signature outputted by QCA cannot be 0069 verified by merely performing RSA and SHA1 operations (e.g. 0070 "openssl rsautl -verify" and comparing with sha1sum), because that would not 0071 take the EMSA3 payload format into consideration. 0072 */ 0073 enum SignatureAlgorithm 0074 { 0075 SignatureUnknown, ///< Unknown signing algorithm 0076 EMSA1_SHA1, ///< SHA1, with EMSA1 (IEEE1363-2000) encoding (this is the usual DSA algorithm - FIPS186) 0077 EMSA3_SHA1, ///< SHA1, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0078 EMSA3_MD5, ///< MD5, with EMSA3 (ie PKCS#1 Version 1.5) encoding (this is the usual RSA algorithm) 0079 EMSA3_MD2, ///< MD2, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0080 EMSA3_RIPEMD160, ///< RIPEMD160, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0081 EMSA3_Raw, ///< EMSA3 without computing a message digest or a DigestInfo encoding (identical to PKCS#11's 0082 ///< CKM_RSA_PKCS mechanism) 0083 EMSA3_SHA224, ///< SHA224, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0084 EMSA3_SHA256, ///< SHA256, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0085 EMSA3_SHA384, ///< SHA384, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0086 EMSA3_SHA512 ///< SHA512, with EMSA3 (ie PKCS#1 Version 1.5) encoding 0087 }; 0088 0089 /** 0090 Signature formats (DSA only) 0091 */ 0092 enum SignatureFormat 0093 { 0094 DefaultFormat, ///< For DSA, this is the same as IEEE_1363 0095 IEEE_1363, ///< 40-byte format from IEEE 1363 (Botan/.NET) 0096 DERSequence ///< Signature wrapped in DER formatting (OpenSSL/Java) 0097 }; 0098 0099 /** 0100 Password-based encryption 0101 */ 0102 enum PBEAlgorithm 0103 { 0104 PBEDefault, ///< Use modern default (same as PBES2_TripleDES_SHA1) 0105 PBES2_DES_SHA1, ///< PKCS#5 v2.0 DES/CBC,SHA1 0106 PBES2_TripleDES_SHA1, ///< PKCS#5 v2.0 TripleDES/CBC,SHA1 0107 PBES2_AES128_SHA1, ///< PKCS#5 v2.0 AES-128/CBC,SHA1 0108 PBES2_AES192_SHA1, ///< PKCS#5 v2.0 AES-192/CBC,SHA1 0109 PBES2_AES256_SHA1 ///< PKCS#5 v2.0 AES-256/CBC,SHA1 0110 }; 0111 0112 /** 0113 Return value from a format conversion 0114 0115 Note that if you are checking for any result other than ConvertGood, 0116 then you may be introducing a provider specific dependency. 0117 */ 0118 enum ConvertResult 0119 { 0120 ConvertGood, ///< Conversion succeeded, results should be valid 0121 ErrorDecode, ///< General failure in the decode stage 0122 ErrorPassphrase, ///< Failure because of incorrect passphrase 0123 ErrorFile ///< Failure because of incorrect file 0124 }; 0125 0126 /** 0127 Well known discrete logarithm group sets 0128 0129 These sets are derived from three main sources: 0130 Java Cryptographic Extensions, 0131 <a href="http://www.ietf.org/rfc/rfc2412.txt">RFC2412</a> and 0132 <a href="http://www.ietf.org/rfc/rfc3526.txt">RFC3526</a>. 0133 */ 0134 enum DLGroupSet 0135 { 0136 DSA_512, ///< 512 bit group, for compatibility with JCE 0137 DSA_768, ///< 768 bit group, for compatibility with JCE 0138 DSA_1024, ///< 1024 bit group, for compatibility with JCE 0139 IETF_768, ///< Group 1 from RFC 2412, Section E.1 0140 IETF_1024, ///< Group 2 from RFC 2412, Section E.2 0141 IETF_1536, ///< 1536-bit MODP Group ("group 5") from RFC3526 Section 2. 0142 IETF_2048, ///< 2048-bit MODP Group ("group 14") from RFC3526 Section 3. 0143 IETF_3072, ///< 3072-bit MODP Group ("group 15") from RFC3526 Section 4. 0144 IETF_4096, ///< 4096-bit MODP Group ("group 16") from RFC3526 Section 5. 0145 IETF_6144, ///< 6144-bit MODP Group ("group 17") from RFC3526 Section 6. 0146 IETF_8192 ///< 8192-bit MODP Group ("group 18") from RFC3526 Section 7. 0147 0148 }; 0149 0150 /** 0151 Encode a hash result in EMSA3 (PKCS#1) format 0152 0153 This is a convenience function for providers that only have access 0154 to raw RSA signing (mainly smartcard providers). This is a built-in 0155 function of QCA and does not utilize a provider. SHA1, MD5, MD2, 0156 and RIPEMD160 are supported. 0157 0158 \param hashName the hash type used to create the digest 0159 \param digest the digest to encode in EMSA3 format 0160 \param size the desired size of the encoding output (-1 for automatic size) 0161 */ 0162 QCA_EXPORT QByteArray emsa3Encode(const QString &hashName, const QByteArray &digest, int size = -1); 0163 0164 /** 0165 \class DLGroup qca_publickey.h QtCrypto 0166 0167 A discrete logarithm group 0168 0169 \ingroup UserAPI 0170 */ 0171 class QCA_EXPORT DLGroup 0172 { 0173 public: 0174 DLGroup(); 0175 0176 /** 0177 Construct a discrete logarithm group from raw parameters 0178 0179 \param p the P parameter 0180 \param q the Q parameter 0181 \param g the G parameter 0182 */ 0183 DLGroup(const BigInteger &p, const BigInteger &q, const BigInteger &g); 0184 0185 /** 0186 Construct a discrete logarithm group from raw parameters 0187 0188 \param p the P parameter 0189 \param g the G parameter 0190 */ 0191 DLGroup(const BigInteger &p, const BigInteger &g); 0192 0193 /** 0194 Standard copy constructor 0195 0196 \param from the group to copy from 0197 */ 0198 DLGroup(const DLGroup &from); 0199 ~DLGroup(); 0200 0201 /** 0202 Standard assignment operator 0203 0204 \param from the DLGroup to copy from 0205 */ 0206 DLGroup &operator=(const DLGroup &from); 0207 0208 /** 0209 Provide a list of the supported group sets 0210 0211 \param provider the provider to report which group sets are 0212 available. If not specified, all providers will be checked 0213 */ 0214 static QList<DLGroupSet> supportedGroupSets(const QString &provider = QString()); 0215 0216 /** 0217 Test if the group is empty 0218 */ 0219 bool isNull() const; 0220 0221 /** 0222 Provide the p component of the group 0223 */ 0224 BigInteger p() const; 0225 0226 /** 0227 Provide the q component of the group 0228 */ 0229 BigInteger q() const; 0230 0231 /** 0232 Provide the g component of the group 0233 */ 0234 BigInteger g() const; 0235 0236 private: 0237 class Private; 0238 Private *d; 0239 }; 0240 0241 /** 0242 \class PKey qca_publickey.h QtCrypto 0243 0244 General superclass for public (PublicKey) and private (PrivateKey) keys 0245 used with asymmetric encryption techniques. 0246 0247 \ingroup UserAPI 0248 0249 */ 0250 class QCA_EXPORT PKey : public Algorithm 0251 { 0252 public: 0253 /** 0254 Types of public key cryptography keys supported by QCA 0255 */ 0256 enum Type 0257 { 0258 RSA, ///< RSA key 0259 DSA, ///< DSA key 0260 DH ///< Diffie Hellman key 0261 }; 0262 0263 /** 0264 Standard constructor 0265 */ 0266 PKey(); 0267 0268 /** 0269 Standard copy constructor 0270 0271 \param from the key to copy from 0272 */ 0273 PKey(const PKey &from); 0274 0275 ~PKey() override; 0276 0277 /** 0278 Standard assignment operator 0279 0280 \param from the PKey to copy from 0281 */ 0282 PKey &operator=(const PKey &from); 0283 0284 /** 0285 Test what types of keys are supported. 0286 0287 Normally you would just test if the capability is present, however 0288 for PKey, you also need to test which types of keys are available. 0289 So if you want to figure out if RSA keys are supported, you need to 0290 do something like: 0291 \code 0292 if(!QCA::isSupported("pkey") || 0293 !QCA::PKey::supportedTypes().contains(QCA::PKey::RSA)) 0294 { 0295 // then there is no RSA key support 0296 } 0297 else 0298 { 0299 // there is RSA key support 0300 } 0301 \endcode 0302 0303 To make things a bit more complex, supportedTypes() only 0304 checks for basic functionality. If you want to check that 0305 you can do operations with PEM or DER (eg toPEM(), fromPEM(), and 0306 the equivalent DER and PEMfile operations, plus anything else 0307 that uses them, including the constructor form that takes a 0308 fileName), then you need to check for supportedIOTypes() instead. 0309 0310 \param provider the name of the provider to use, if a particular 0311 provider is required. 0312 0313 \sa supportedIOTypes() 0314 */ 0315 static QList<Type> supportedTypes(const QString &provider = QString()); 0316 0317 /** 0318 Test what types of keys are supported for IO operations 0319 0320 If you are using PKey DER or PEM operations, then you need 0321 to check for appropriate support using this method. For example, 0322 if you want to check if you can export or import an RSA key, then 0323 you need to do something like: 0324 \code 0325 if(!QCA::isSupported("pkey") || 0326 !QCA::PKey::supportedIOTypes().contains(QCA::PKey::RSA)) 0327 { 0328 // then there is no RSA key IO support 0329 } 0330 else 0331 { 0332 // there is RSA key IO support 0333 } 0334 \endcode 0335 0336 Note that if you only want to check for basic functionality 0337 (ie not PEM or DER import/export), then you can use 0338 supportedTypes(). There is no need to use both - if the key type 0339 is supported for IO, then is also supported for basic operations. 0340 0341 \param provider the name of the provider to use, if a particular 0342 provider is required. 0343 0344 \sa supportedTypes() 0345 */ 0346 static QList<Type> supportedIOTypes(const QString &provider = QString()); 0347 0348 /** 0349 Test if the key is null (empty) 0350 0351 \return true if the key is null 0352 */ 0353 bool isNull() const; 0354 0355 /** 0356 Report the Type of key (eg RSA, DSA or Diffie Hellman) 0357 0358 \sa isRSA, isDSA and isDH for boolean tests. 0359 */ 0360 Type type() const; 0361 0362 /** 0363 Report the number of bits in the key 0364 */ 0365 int bitSize() const; 0366 0367 /** 0368 Test if the key is an RSA key 0369 */ 0370 bool isRSA() const; 0371 0372 /** 0373 Test if the key is a DSA key 0374 */ 0375 bool isDSA() const; 0376 0377 /** 0378 Test if the key is a Diffie Hellman key 0379 */ 0380 bool isDH() const; 0381 0382 /** 0383 Test if the key is a public key 0384 */ 0385 bool isPublic() const; 0386 0387 /** 0388 Test if the key is a private key 0389 */ 0390 bool isPrivate() const; 0391 0392 /** 0393 Test if the key data can be exported. If the key resides on a 0394 smart card or other such device, this will likely return false. 0395 */ 0396 bool canExport() const; 0397 0398 /** 0399 Test if the key can be used for key agreement 0400 */ 0401 bool canKeyAgree() const; 0402 0403 /** 0404 Interpret this key as a PublicKey 0405 0406 \sa toRSAPublicKey(), toDSAPublicKey() and toDHPublicKey() 0407 for protected forms of this call. 0408 */ 0409 PublicKey toPublicKey() const; 0410 0411 /** 0412 Interpret this key as a PrivateKey 0413 */ 0414 PrivateKey toPrivateKey() const; 0415 0416 /** 0417 test if two keys are equal 0418 0419 \param a the key to compare with this key 0420 */ 0421 bool operator==(const PKey &a) const; 0422 0423 /** 0424 test if two keys are not equal 0425 0426 \param a the key to compare with this key 0427 */ 0428 bool operator!=(const PKey &a) const; 0429 0430 protected: 0431 /** 0432 Create a key of the specified type 0433 0434 \param type the name of the type of key to create 0435 \param provider the name of the provider to create the key in 0436 */ 0437 PKey(const QString &type, const QString &provider); 0438 0439 /** 0440 Set the key 0441 0442 \param k the key to assign from 0443 */ 0444 void set(const PKey &k); 0445 0446 /** 0447 Interpret this key as an RSAPublicKey 0448 0449 \note This function is essentially a convenience cast - if the 0450 key was created as a DSA key, this function cannot turn it into 0451 an RSA key. 0452 0453 \sa toPublicKey() for the public version of this method 0454 */ 0455 RSAPublicKey toRSAPublicKey() const; 0456 0457 /** 0458 Interpret this key as an RSAPrivateKey 0459 0460 \note This function is essentially a convenience cast - if the 0461 key was created as a DSA key, this function cannot turn it into 0462 a RSA key. 0463 0464 \sa toPrivateKey() for the public version of this method 0465 */ 0466 RSAPrivateKey toRSAPrivateKey() const; 0467 0468 /** 0469 Interpret this key as an DSAPublicKey 0470 0471 \note This function is essentially a convenience cast - if the 0472 key was created as an RSA key, this function cannot turn it into 0473 a DSA key. 0474 0475 \sa toPublicKey() for the public version of this method 0476 */ 0477 DSAPublicKey toDSAPublicKey() const; 0478 0479 /** 0480 Interpret this key as a DSAPrivateKey 0481 0482 \note This function is essentially a convenience cast - if the 0483 key was created as an RSA key, this function cannot turn it into 0484 a DSA key. 0485 0486 \sa toPrivateKey() for the public version of this method 0487 */ 0488 DSAPrivateKey toDSAPrivateKey() const; 0489 0490 /** 0491 Interpret this key as an DHPublicKey 0492 0493 \note This function is essentially a convenience cast - if the 0494 key was created as a DSA key, this function cannot turn it into 0495 a DH key. 0496 0497 \sa toPublicKey() for the public version of this method 0498 */ 0499 DHPublicKey toDHPublicKey() const; 0500 0501 /** 0502 Interpret this key as a DHPrivateKey 0503 0504 \note This function is essentially a convenience cast - if the 0505 key was created as a DSA key, this function cannot turn it into 0506 a DH key. 0507 0508 \sa toPrivateKey() for the public version of this method 0509 */ 0510 DHPrivateKey toDHPrivateKey() const; 0511 0512 private: 0513 void assignToPublic(PKey *dest) const; 0514 void assignToPrivate(PKey *dest) const; 0515 0516 class Private; 0517 Private *d; 0518 }; 0519 0520 /** 0521 \class PublicKey qca_publickey.h QtCrypto 0522 0523 Generic public key 0524 0525 \ingroup UserAPI 0526 0527 */ 0528 class QCA_EXPORT PublicKey : public PKey 0529 { 0530 public: 0531 /** 0532 Create an empty (null) public key 0533 */ 0534 PublicKey(); 0535 0536 /** 0537 Create a public key based on a specified private key 0538 0539 \param k the private key to extract the public key parts from 0540 */ 0541 PublicKey(const PrivateKey &k); 0542 0543 /** 0544 Import a public key from a PEM representation in a file 0545 0546 \param fileName the name of the file containing the public key 0547 0548 \sa fromPEMFile for an alternative method 0549 */ 0550 PublicKey(const QString &fileName); 0551 0552 /** 0553 Copy constructor 0554 0555 \param from the PublicKey to copy from 0556 */ 0557 PublicKey(const PublicKey &from); 0558 0559 ~PublicKey() override; 0560 0561 /** 0562 Assignment operator 0563 0564 \param from the PublicKey to copy from 0565 */ 0566 PublicKey &operator=(const PublicKey &from); 0567 0568 /** 0569 Convenience method to convert this key to an RSAPublicKey 0570 0571 Note that if the key is not an RSA key (eg it is DSA or DH), 0572 then this will produce a null key. 0573 */ 0574 RSAPublicKey toRSA() const; 0575 0576 /** 0577 Convenience method to convert this key to a DSAPublicKey 0578 0579 Note that if the key is not an DSA key (eg it is RSA or DH), 0580 then this will produce a null key. 0581 */ 0582 DSAPublicKey toDSA() const; 0583 0584 /** 0585 Convenience method to convert this key to a DHPublicKey 0586 0587 Note that if the key is not an DH key (eg it is DSA or RSA), 0588 then this will produce a null key. 0589 */ 0590 DHPublicKey toDH() const; 0591 0592 /** 0593 Test if this key can be used for encryption 0594 0595 \return true if the key can be used for encryption 0596 */ 0597 bool canEncrypt() const; 0598 0599 /** 0600 Test if this key can be used for decryption 0601 0602 \return true if the key can be used for decryption 0603 */ 0604 bool canDecrypt() const; 0605 0606 /** 0607 Test if the key can be used for verifying signatures 0608 0609 \return true of the key can be used for verification 0610 */ 0611 bool canVerify() const; 0612 0613 /** 0614 The maximum message size that can be encrypted with a specified 0615 algorithm 0616 0617 \param alg the algorithm to check 0618 */ 0619 int maximumEncryptSize(EncryptionAlgorithm alg) const; 0620 0621 /** 0622 Encrypt a message using a specified algorithm 0623 0624 \param a the message to encrypt 0625 \param alg the algorithm to use 0626 */ 0627 SecureArray encrypt(const SecureArray &a, EncryptionAlgorithm alg); 0628 0629 /** 0630 Decrypt the message 0631 0632 \param in the cipher (encrypted) data 0633 \param out the plain text data 0634 \param alg the algorithm to use 0635 0636 \note This synchronous operation may require event handling, and so 0637 it must not be called from the same thread as an EventHandler. 0638 */ 0639 bool decrypt(const SecureArray &in, SecureArray *out, EncryptionAlgorithm alg); 0640 0641 /** 0642 Initialise the signature verification process 0643 0644 \param alg the algorithm to use for signing 0645 \param format the specific format to use, for DSA 0646 */ 0647 void startVerify(SignatureAlgorithm alg, SignatureFormat format = DefaultFormat); 0648 0649 /** 0650 Update the signature verification process with more data 0651 0652 \param a the array containing the data that should be added to the signature 0653 */ 0654 void update(const MemoryRegion &a); 0655 0656 /** 0657 Check the signature is valid for the message 0658 0659 The process to check that a signature is correct is shown below: 0660 \code 0661 // note that pubkey is a PublicKey 0662 if( pubkey.canVerify() ) 0663 { 0664 pubkey.startVerify( QCA::EMSA3_MD5 ); 0665 pubkey.update( theMessage ); // might be called multiple times 0666 if ( pubkey.validSignature( theSignature ) ) 0667 { 0668 // then signature is valid 0669 } 0670 else 0671 { 0672 // then signature is invalid 0673 } 0674 } 0675 \endcode 0676 0677 \param sig the signature to check 0678 0679 \return true if the signature is correct 0680 */ 0681 bool validSignature(const QByteArray &sig); 0682 0683 /** 0684 Single step message verification 0685 0686 If you have the whole message to be verified, then this offers a 0687 more convenient approach to verification. 0688 0689 \param a the message to check the signature on 0690 \param sig the signature to be checked 0691 \param alg the algorithm to use 0692 \param format the signature format to use, for DSA 0693 0694 \return true if the signature is valid for the message 0695 */ 0696 bool verifyMessage(const MemoryRegion &a, 0697 const QByteArray &sig, 0698 SignatureAlgorithm alg, 0699 SignatureFormat format = DefaultFormat); 0700 0701 /** 0702 Export the key in Distinguished Encoding Rules (DER) format 0703 */ 0704 QByteArray toDER() const; 0705 0706 /** 0707 Export the key in Privacy Enhanced Mail (PEM) format 0708 0709 \sa toPEMFile provides a convenient way to save the PEM encoded key 0710 to a file 0711 \sa fromPEM provides an inverse of toPEM, converting the PEM 0712 encoded key back to a PublicKey 0713 */ 0714 QString toPEM() const; 0715 0716 /** 0717 Export the key in Privacy Enhanced Mail (PEM) to a file 0718 0719 \param fileName the name (and path, if necessary) of the file to 0720 save the PEM encoded key to. 0721 0722 \sa toPEM for a version that exports to a QString, which may be 0723 useful if you need to do more sophisticated handling 0724 \sa fromPEMFile provides an inverse of toPEMFile, reading a PEM 0725 encoded key from a file 0726 */ 0727 bool toPEMFile(const QString &fileName) const; 0728 0729 /** 0730 Import a key in Distinguished Encoding Rules (DER) format 0731 0732 This function takes a binary array, which is assumed to contain a 0733 public key in DER encoding, and returns the key. Unless you don't 0734 care whether the import succeeded, you should test the result, as 0735 shown below. 0736 0737 \code 0738 QCA::ConvertResult conversionResult; 0739 QCA::PublicKey publicKey = QCA::PublicKey::fromDER(keyArray, &conversionResult); 0740 if (! QCA::ConvertGood == conversionResult) 0741 { 0742 std::cout << "Public key read failed" << std::endl; 0743 } 0744 \endcode 0745 0746 \param a the array containing a DER encoded key 0747 \param result pointer to a variable, which returns whether the 0748 conversion succeeded (ConvertGood) or not 0749 \param provider the name of the provider to use for the import. 0750 */ 0751 static PublicKey fromDER(const QByteArray &a, ConvertResult *result = nullptr, const QString &provider = QString()); 0752 0753 /** 0754 Import a key in Privacy Enhanced Mail (PEM) format 0755 0756 This function takes a string, which is assumed to contain a public 0757 key in PEM encoding, and returns that key. Unless you don't care 0758 whether the import succeeded, you should test the result, as shown 0759 below. 0760 0761 \code 0762 QCA::ConvertResult conversionResult; 0763 QCA::PublicKey publicKey = QCA::PublicKey::fromPEM(keyAsString, &conversionResult); 0764 if (! QCA::ConvertGood == conversionResult) 0765 { 0766 std::cout << "Public key read failed" << std::endl; 0767 } 0768 \endcode 0769 0770 \param s the string containing a PEM encoded key 0771 \param result pointer to a variable, which returns whether the 0772 conversion succeeded (ConvertGood) or not 0773 \param provider the name of the provider to use for the import. 0774 0775 \sa toPEM, which provides an inverse of fromPEM() 0776 \sa fromPEMFile, which provides an import direct from a file. 0777 */ 0778 static PublicKey fromPEM(const QString &s, ConvertResult *result = nullptr, const QString &provider = QString()); 0779 0780 /** 0781 Import a key in Privacy Enhanced Mail (PEM) format from a file 0782 0783 This function takes the name of a file, which is assumed to contain 0784 a public key in PEM encoding, and returns that key. Unless you 0785 don't care whether the import succeeded, you should test the 0786 result, as shown below. 0787 0788 \code 0789 QCA::ConvertResult conversionResult; 0790 QCA::PublicKey publicKey = QCA::PublicKey::fromPEMFile(fileName, &conversionResult); 0791 if (! QCA::ConvertGood == conversionResult) 0792 { 0793 std::cout << "Public key read failed" << std::endl; 0794 } 0795 \endcode 0796 0797 \param fileName a string containing the name of the file 0798 \param result pointer to a variable, which returns whether the 0799 conversion succeeded (ConvertGood) or not 0800 \param provider the name of the provider to use for the import. 0801 0802 \sa toPEMFile, which provides an inverse of fromPEMFile() 0803 \sa fromPEM, which provides an import from a string 0804 0805 \note there is also a constructor form that can import from a file 0806 */ 0807 static PublicKey 0808 fromPEMFile(const QString &fileName, ConvertResult *result = nullptr, const QString &provider = QString()); 0809 0810 protected: 0811 /** 0812 Create a new key of a specified type 0813 0814 \param type the type of key to create 0815 \param provider the provider to use, if required 0816 */ 0817 PublicKey(const QString &type, const QString &provider); 0818 0819 private: 0820 class Private; 0821 Private *d; 0822 }; 0823 0824 /** 0825 \class PrivateKey qca_publickey.h QtCrypto 0826 0827 Generic private key 0828 0829 \ingroup UserAPI 0830 0831 */ 0832 class QCA_EXPORT PrivateKey : public PKey 0833 { 0834 public: 0835 /** 0836 Create an empty private key 0837 */ 0838 PrivateKey(); 0839 0840 /** 0841 Import a private key from a PEM representation in a file 0842 0843 \param fileName the name of the file containing the private key 0844 \param passphrase the pass phrase for the private key 0845 0846 \sa fromPEMFile for an alternative method 0847 0848 \note This synchronous operation may require event handling, and so 0849 it must not be called from the same thread as an EventHandler. 0850 */ 0851 explicit PrivateKey(const QString &fileName, const SecureArray &passphrase = SecureArray()); 0852 0853 /** 0854 Copy constructor 0855 0856 \param from the PrivateKey to copy from 0857 */ 0858 PrivateKey(const PrivateKey &from); 0859 0860 ~PrivateKey() override; 0861 0862 /** 0863 Assignment operator 0864 0865 \param from the PrivateKey to copy from 0866 */ 0867 PrivateKey &operator=(const PrivateKey &from); 0868 0869 /** 0870 Interpret / convert the key to an RSA key 0871 */ 0872 RSAPrivateKey toRSA() const; 0873 0874 /** 0875 Interpret / convert the key to a DSA key 0876 */ 0877 DSAPrivateKey toDSA() const; 0878 0879 /** 0880 Interpret / convert the key to a Diffie-Hellman key 0881 */ 0882 DHPrivateKey toDH() const; 0883 0884 /** 0885 Test if this key can be used for decryption 0886 0887 \return true if the key can be used for decryption 0888 */ 0889 bool canDecrypt() const; 0890 0891 /** 0892 Test if this key can be used for encryption 0893 0894 \return true if the key can be used for encryption 0895 */ 0896 bool canEncrypt() const; 0897 0898 /** 0899 Test if this key can be used for signing 0900 0901 \return true if the key can be used to make a signature 0902 */ 0903 bool canSign() const; 0904 0905 /** 0906 The maximum message size that can be encrypted with a specified 0907 algorithm 0908 0909 \param alg the algorithm to check 0910 */ 0911 int maximumEncryptSize(EncryptionAlgorithm alg) const; 0912 0913 /** 0914 Decrypt the message 0915 0916 \param in the cipher (encrypted) data 0917 \param out the plain text data 0918 \param alg the algorithm to use 0919 0920 \note This synchronous operation may require event handling, and so 0921 it must not be called from the same thread as an EventHandler. 0922 */ 0923 bool decrypt(const SecureArray &in, SecureArray *out, EncryptionAlgorithm alg); 0924 0925 /** 0926 Encrypt a message using a specified algorithm 0927 0928 \param a the message to encrypt 0929 \param alg the algorithm to use 0930 */ 0931 SecureArray encrypt(const SecureArray &a, EncryptionAlgorithm alg); 0932 0933 /** 0934 Initialise the message signature process 0935 0936 \param alg the algorithm to use for the message signature process 0937 \param format the signature format to use, for DSA 0938 0939 \note This synchronous operation may require event handling, and so 0940 it must not be called from the same thread as an EventHandler. 0941 */ 0942 void startSign(SignatureAlgorithm alg, SignatureFormat format = DefaultFormat); 0943 0944 /** 0945 Update the signature process 0946 0947 \param a the message to use to update the signature 0948 0949 \note This synchronous operation may require event handling, and so 0950 it must not be called from the same thread as an EventHandler. 0951 */ 0952 void update(const MemoryRegion &a); 0953 0954 /** 0955 The resulting signature 0956 0957 \note This synchronous operation may require event handling, and so 0958 it must not be called from the same thread as an EventHandler. 0959 */ 0960 QByteArray signature(); 0961 0962 /** 0963 One step signature process 0964 0965 \param a the message to sign 0966 \param alg the algorithm to use for the signature 0967 \param format the signature format to use, for DSA 0968 0969 \return the signature 0970 0971 \note This synchronous operation may require event handling, and so 0972 it must not be called from the same thread as an EventHandler. 0973 */ 0974 QByteArray signMessage(const MemoryRegion &a, SignatureAlgorithm alg, SignatureFormat format = DefaultFormat); 0975 0976 /** 0977 Derive a shared secret key from a public key 0978 0979 \param theirs the public key to derive from 0980 */ 0981 SymmetricKey deriveKey(const PublicKey &theirs); 0982 0983 /** 0984 List the supported Password Based Encryption Algorithms that can be 0985 used to protect the key. 0986 0987 \param provider the provider to use, if a particular provider is 0988 required 0989 */ 0990 static QList<PBEAlgorithm> supportedPBEAlgorithms(const QString &provider = QString()); 0991 0992 /** 0993 Export the key in Distinguished Encoding Rules (DER) format 0994 0995 \param passphrase the pass phrase to use to protect the key 0996 \param pbe the symmetric encryption algorithm to use to protect the 0997 key 0998 0999 \sa fromDER provides an inverse of toDER, converting the DER 1000 encoded key back to a PrivateKey 1001 */ 1002 SecureArray toDER(const SecureArray &passphrase = SecureArray(), PBEAlgorithm pbe = PBEDefault) const; 1003 1004 /** 1005 Export the key in Privacy Enhanced Mail (PEM) format 1006 1007 \param passphrase the pass phrase to use to protect the key 1008 \param pbe the symmetric encryption algorithm to use to protect the 1009 key 1010 1011 \sa toPEMFile provides a convenient way to save the PEM encoded key 1012 to a file 1013 \sa fromPEM provides an inverse of toPEM, converting the PEM 1014 encoded key back to a PrivateKey 1015 */ 1016 QString toPEM(const SecureArray &passphrase = SecureArray(), PBEAlgorithm pbe = PBEDefault) const; 1017 1018 /** 1019 Export the key in Privacy Enhanced Mail (PEM) format to a file 1020 1021 \param fileName the name (and path, if required) that the key 1022 should be exported to. 1023 \param passphrase the pass phrase to use to protect the key 1024 \param pbe the symmetric encryption algorithm to use to protect the 1025 key 1026 1027 \return true if the export succeeds 1028 1029 \sa toPEM provides a convenient way to save the PEM encoded key to 1030 a file 1031 \sa fromPEM provides an inverse of toPEM, converting the PEM 1032 encoded key back to a PrivateKey 1033 */ 1034 bool toPEMFile(const QString &fileName, 1035 const SecureArray &passphrase = SecureArray(), 1036 PBEAlgorithm pbe = PBEDefault) const; 1037 1038 /** 1039 Import the key from Distinguished Encoding Rules (DER) format 1040 1041 \param a the array containing the DER representation of the key 1042 \param passphrase the pass phrase that is used to protect the key 1043 \param result a pointer to a ConvertResult, that if specified, will 1044 be set to reflect the result of the import 1045 \param provider the provider to use, if a particular provider is 1046 required 1047 1048 \sa toDER provides an inverse of fromDER, exporting the key to an 1049 array 1050 1051 \sa QCA::KeyLoader for an asynchronous loader approach. 1052 1053 \note This synchronous operation may require event handling, and so 1054 it must not be called from the same thread as an EventHandler. 1055 */ 1056 static PrivateKey fromDER(const SecureArray &a, 1057 const SecureArray &passphrase = SecureArray(), 1058 ConvertResult *result = nullptr, 1059 const QString &provider = QString()); 1060 1061 /** 1062 Import the key from Privacy Enhanced Mail (PEM) format 1063 1064 \param s the string containing the PEM representation of the key 1065 \param passphrase the pass phrase that is used to protect the key 1066 \param result a pointer to a ConvertResult, that if specified, will 1067 be set to reflect the result of the import 1068 \param provider the provider to use, if a particular provider is 1069 required 1070 1071 \sa toPEM provides an inverse of fromPEM, exporting the key to a 1072 string in PEM encoding. 1073 1074 \sa QCA::KeyLoader for an asynchronous loader approach. 1075 1076 \note This synchronous operation may require event handling, and so 1077 it must not be called from the same thread as an EventHandler. 1078 */ 1079 static PrivateKey fromPEM(const QString &s, 1080 const SecureArray &passphrase = SecureArray(), 1081 ConvertResult *result = nullptr, 1082 const QString &provider = QString()); 1083 1084 /** 1085 Import the key in Privacy Enhanced Mail (PEM) format from a file 1086 1087 \param fileName the name (and path, if required) of the file 1088 containing the PEM representation of the key 1089 \param passphrase the pass phrase that is used to protect the key 1090 \param result a pointer to a ConvertResult, that if specified, will 1091 be set to reflect the result of the import 1092 \param provider the provider to use, if a particular provider is 1093 required 1094 1095 \sa toPEMFile provides an inverse of fromPEMFile 1096 \sa fromPEM which allows import from a string 1097 1098 \sa QCA::KeyLoader for an asynchronous loader approach. 1099 1100 \note there is also a constructor form, that allows you to create 1101 the key directly 1102 1103 \note This synchronous operation may require event handling, and so 1104 it must not be called from the same thread as an EventHandler. 1105 */ 1106 static PrivateKey fromPEMFile(const QString &fileName, 1107 const SecureArray &passphrase = SecureArray(), 1108 ConvertResult *result = nullptr, 1109 const QString &provider = QString()); 1110 1111 protected: 1112 /** 1113 Create a new private key 1114 1115 \param type the type of key to create 1116 \param provider the provider to use, if a specific provider is 1117 required. 1118 */ 1119 PrivateKey(const QString &type, const QString &provider); 1120 1121 private: 1122 class Private; 1123 Private *d; 1124 }; 1125 1126 /** 1127 \class KeyGenerator qca_publickey.h QtCrypto 1128 1129 Class for generating asymmetric key pairs 1130 1131 This class is used for generating asymmetric keys (public/private key 1132 pairs). 1133 1134 \ingroup UserAPI 1135 1136 */ 1137 class QCA_EXPORT KeyGenerator : public QObject 1138 { 1139 Q_OBJECT 1140 public: 1141 /** 1142 Create a new key generator 1143 1144 \param parent the parent object, if applicable 1145 */ 1146 KeyGenerator(QObject *parent = nullptr); 1147 1148 ~KeyGenerator() override; 1149 1150 /** 1151 Test whether the key generator is set to operate in blocking mode, 1152 or not 1153 1154 \return true if the key generator is in blocking mode 1155 1156 \sa setBlockingEnabled 1157 */ 1158 bool blockingEnabled() const; 1159 1160 /** 1161 Set whether the key generator is in blocking mode, nor not 1162 1163 \param b if true, the key generator will be set to operate in 1164 blocking mode, otherwise it will operate in non-blocking mode 1165 1166 \sa blockingEnabled() 1167 */ 1168 void setBlockingEnabled(bool b); 1169 1170 /** 1171 Test if the key generator is currently busy, or not 1172 1173 \return true if the key generator is busy generating a key already 1174 */ 1175 bool isBusy() const; 1176 1177 /** 1178 Generate an RSA key of the specified length 1179 1180 This method creates both the public key and corresponding private 1181 key. You almost certainly want to extract the public key part out - 1182 see PKey::toPublicKey for an easy way. 1183 1184 Key length is a tricky judgment - using less than 2048 is probably 1185 being too liberal for long term use. Don't use less than 1024 1186 without serious analysis. 1187 1188 \param bits the length of key that is required 1189 \param exp the exponent - typically 3, 17 or 65537 1190 \param provider the name of the provider to use, if a particular 1191 provider is required 1192 */ 1193 PrivateKey createRSA(int bits, int exp = 65537, const QString &provider = QString()); 1194 1195 /** 1196 Generate a DSA key 1197 1198 This method creates both the public key and corresponding private 1199 key. You almost certainly want to extract the public key part out - 1200 see PKey::toPublicKey for an easy way. 1201 1202 \param domain the discrete logarithm group that this key should be 1203 generated from 1204 \param provider the name of the provider to use, if a particular 1205 provider is required 1206 1207 \note Not every DLGroup makes sense for DSA. You should use one of 1208 DSA_512, DSA_768 and DSA_1024. 1209 */ 1210 PrivateKey createDSA(const DLGroup &domain, const QString &provider = QString()); 1211 1212 /** 1213 Generate a Diffie-Hellman key 1214 1215 This method creates both the public key and corresponding private 1216 key. You almost certainly want to extract the public key part out - 1217 see PKey::toPublicKey for an easy way. 1218 1219 \param domain the discrete logarithm group that this key should be 1220 generated from 1221 \param provider the name of the provider to use, if a particular 1222 provider is required 1223 \note For compatibility, you should use one of the IETF_ groupsets 1224 as the domain argument. 1225 */ 1226 PrivateKey createDH(const DLGroup &domain, const QString &provider = QString()); 1227 1228 /** 1229 Return the last generated key 1230 1231 This is really only useful when you are working with non-blocking 1232 key generation 1233 */ 1234 PrivateKey key() const; 1235 1236 /** 1237 Create a new discrete logarithm group 1238 1239 \param set the set of discrete logarithm parameters to generate 1240 from 1241 \param provider the name of the provider to use, if a particular 1242 provider is required. 1243 */ 1244 DLGroup createDLGroup(QCA::DLGroupSet set, const QString &provider = QString()); 1245 1246 /** 1247 The current discrete logarithm group 1248 */ 1249 DLGroup dlGroup() const; 1250 1251 Q_SIGNALS: 1252 /** 1253 Emitted when the key generation is complete. 1254 1255 This is only used in non-blocking mode 1256 */ 1257 void finished(); 1258 1259 private: 1260 Q_DISABLE_COPY(KeyGenerator) 1261 1262 class Private; 1263 friend class Private; 1264 Private *d; 1265 }; 1266 1267 /** 1268 \class RSAPublicKey qca_publickey.h QtCrypto 1269 1270 RSA Public Key 1271 1272 \ingroup UserAPI 1273 1274 */ 1275 class QCA_EXPORT RSAPublicKey : public PublicKey 1276 { 1277 public: 1278 /** 1279 Generate an empty RSA public key 1280 */ 1281 RSAPublicKey(); 1282 1283 /** 1284 Generate an RSA public key from specified parameters 1285 1286 \param n the public key value 1287 \param e the public key exponent 1288 \param provider the provider to use, if a particular provider is 1289 required 1290 */ 1291 RSAPublicKey(const BigInteger &n, const BigInteger &e, const QString &provider = QString()); 1292 1293 /** 1294 Extract the public key components from an RSA private key 1295 1296 \param k the private key to use as the basis for the public key 1297 */ 1298 RSAPublicKey(const RSAPrivateKey &k); 1299 1300 /** 1301 The public key value 1302 1303 This value is the actual public key value (the product of p and q, 1304 the random prime numbers used to generate the RSA key), also known 1305 as the public modulus. 1306 */ 1307 BigInteger n() const; 1308 1309 /** 1310 The public key exponent 1311 1312 This value is the exponent chosen in the original key generator 1313 step 1314 */ 1315 BigInteger e() const; 1316 }; 1317 1318 /** 1319 \class RSAPrivateKey qca_publickey.h QtCrypto 1320 1321 RSA Private Key 1322 1323 \ingroup UserAPI 1324 1325 */ 1326 class QCA_EXPORT RSAPrivateKey : public PrivateKey 1327 { 1328 public: 1329 /** 1330 Generate an empty RSA private key 1331 */ 1332 RSAPrivateKey(); 1333 1334 /** 1335 Generate an RSA private key from specified parameters 1336 1337 \param n the public key value 1338 \param e the public key exponent 1339 \param p one of the two chosen primes 1340 \param q the other of the two chosen primes 1341 \param d inverse of the exponent, modulo (p-1)(q-1) 1342 \param provider the provider to use, if a particular provider is 1343 required 1344 */ 1345 RSAPrivateKey(const BigInteger &n, 1346 const BigInteger &e, 1347 const BigInteger &p, 1348 const BigInteger &q, 1349 const BigInteger &d, 1350 const QString &provider = QString()); 1351 1352 /** 1353 The public key value 1354 1355 This value is the actual public key value (the product of p and q, 1356 the random prime numbers used to generate the RSA key), also known 1357 as the public modulus. 1358 */ 1359 BigInteger n() const; 1360 1361 /** 1362 The public key exponent 1363 1364 This value is the exponent chosen in the original key generator 1365 step 1366 */ 1367 BigInteger e() const; 1368 1369 /** 1370 One of the two random primes used to generate the private key 1371 */ 1372 BigInteger p() const; 1373 1374 /** 1375 The second of the two random primes used to generate the private 1376 key 1377 */ 1378 BigInteger q() const; 1379 1380 /** 1381 The inverse of the exponent, module (p-1)(q-1) 1382 */ 1383 BigInteger d() const; 1384 }; 1385 1386 /** 1387 \class DSAPublicKey qca_publickey.h QtCrypto 1388 1389 Digital Signature %Algorithm Public Key 1390 1391 \ingroup UserAPI 1392 1393 */ 1394 class QCA_EXPORT DSAPublicKey : public PublicKey 1395 { 1396 public: 1397 /** 1398 Create an empty DSA public key 1399 */ 1400 DSAPublicKey(); 1401 1402 /** 1403 Create a DSA public key 1404 1405 \param domain the discrete logarithm group to use 1406 \param y the public random value 1407 \param provider the provider to use, if a specific provider is 1408 required 1409 */ 1410 DSAPublicKey(const DLGroup &domain, const BigInteger &y, const QString &provider = QString()); 1411 1412 /** 1413 Create a DSA public key from a specified private key 1414 1415 \param k the DSA private key to use as the source 1416 */ 1417 DSAPublicKey(const DSAPrivateKey &k); 1418 1419 /** 1420 The discrete logarithm group that is being used 1421 */ 1422 DLGroup domain() const; 1423 1424 /** 1425 The public random value associated with this key 1426 */ 1427 BigInteger y() const; 1428 }; 1429 1430 /** 1431 \class DSAPrivateKey qca_publickey.h QtCrypto 1432 1433 Digital Signature %Algorithm Private Key 1434 1435 \ingroup UserAPI 1436 1437 */ 1438 class QCA_EXPORT DSAPrivateKey : public PrivateKey 1439 { 1440 public: 1441 /** 1442 Create an empty DSA private key 1443 */ 1444 DSAPrivateKey(); 1445 1446 /** 1447 Create a DSA public key 1448 1449 \param domain the discrete logarithm group to use 1450 \param y the public random value 1451 \param x the private random value 1452 \param provider the provider to use, if a specific provider is 1453 required 1454 */ 1455 DSAPrivateKey(const DLGroup &domain, const BigInteger &y, const BigInteger &x, const QString &provider = QString()); 1456 1457 /** 1458 The discrete logarithm group that is being used 1459 */ 1460 DLGroup domain() const; 1461 1462 /** 1463 the public random value 1464 */ 1465 BigInteger y() const; 1466 1467 /** 1468 the private random value 1469 */ 1470 BigInteger x() const; 1471 }; 1472 1473 /** 1474 \class DHPublicKey qca_publickey.h QtCrypto 1475 1476 Diffie-Hellman Public Key 1477 1478 \ingroup UserAPI 1479 1480 */ 1481 class QCA_EXPORT DHPublicKey : public PublicKey 1482 { 1483 public: 1484 /** 1485 Create an empty Diffie-Hellman public key 1486 */ 1487 DHPublicKey(); 1488 1489 /** 1490 Create a Diffie-Hellman public key 1491 1492 \param domain the discrete logarithm group to use 1493 \param y the public random value 1494 \param provider the provider to use, if a specific provider is 1495 required 1496 */ 1497 DHPublicKey(const DLGroup &domain, const BigInteger &y, const QString &provider = QString()); 1498 1499 /** 1500 Create a Diffie-Hellman public key from a specified private key 1501 1502 \param k the Diffie-Hellman private key to use as the source 1503 */ 1504 DHPublicKey(const DHPrivateKey &k); 1505 1506 /** 1507 The discrete logarithm group that is being used 1508 */ 1509 DLGroup domain() const; 1510 1511 /** 1512 The public random value associated with this key 1513 */ 1514 BigInteger y() const; 1515 }; 1516 1517 /** 1518 \class DHPrivateKey qca_publickey.h QtCrypto 1519 1520 Diffie-Hellman Private Key 1521 1522 \ingroup UserAPI 1523 1524 */ 1525 class QCA_EXPORT DHPrivateKey : public PrivateKey 1526 { 1527 public: 1528 /** 1529 Create an empty Diffie-Hellman private key 1530 */ 1531 DHPrivateKey(); 1532 1533 /** 1534 Create a Diffie-Hellman private key 1535 1536 \param domain the discrete logarithm group to use 1537 \param y the public random value 1538 \param x the private random value 1539 \param provider the provider to use, if a particular provider is 1540 required 1541 */ 1542 DHPrivateKey(const DLGroup &domain, const BigInteger &y, const BigInteger &x, const QString &provider = QString()); 1543 1544 /** 1545 The discrete logarithm group that is being used 1546 */ 1547 DLGroup domain() const; 1548 1549 /** 1550 The public random value associated with this key 1551 */ 1552 BigInteger y() const; 1553 1554 /** 1555 The private random value associated with this key 1556 */ 1557 BigInteger x() const; 1558 }; 1559 /*@}*/ 1560 } 1561 1562 #endif