1/*
2 * qca_publickey.h - Qt Cryptographic Architecture
3 * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com>
4 * Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 * 02110-1301 USA
20 *
21 */
22
23/**
24 \file qca_publickey.h
25
26 Header file for PublicKey and PrivateKey related classes
27
28 \note You should not use this header directly from an
29 application. You should just use <tt> \#include \<QtCrypto>
30 </tt> instead.
31*/
32
33#ifndef QCA_PUBLICKEY_H
34#define QCA_PUBLICKEY_H
35
36#include "qca_core.h"
37#include <QObject>
38
39namespace QCA {
40
41class PublicKey;
42class PrivateKey;
43class KeyGenerator;
44class RSAPublicKey;
45class RSAPrivateKey;
46class DSAPublicKey;
47class DSAPrivateKey;
48class DHPublicKey;
49class DHPrivateKey;
50
51/**
52 Encryption algorithms
53*/
54enum EncryptionAlgorithm
55{
56 EME_PKCS1v15, ///< Block type 2 (PKCS#1, Version 1.5)
57 EME_PKCS1_OAEP, ///< Optimal asymmetric encryption padding (PKCS#1, Version 2.0)
58 EME_PKCS1v15_SSL, ///< PKCS#1, Version 1.5 with an SSL-specific modification
59 EME_NO_PADDING ///< Raw RSA encryption
60};
61
62/**
63 Signature algorithm variants
64
65 Note that most signature algorithms follow a process of first hashing the
66 plaintext data to be signed, creating a payload format that wraps the hash
67 value (among other things), and then signing the payload with the private
68 key. So, for example, an EMSA3(SHA1) signature outputted by QCA cannot be
69 verified by merely performing RSA and SHA1 operations (e.g.
70 "openssl rsautl -verify" and comparing with sha1sum), because that would not
71 take the EMSA3 payload format into consideration.
72*/
73enum SignatureAlgorithm
74{
75 SignatureUnknown, ///< Unknown signing algorithm
76 EMSA1_SHA1, ///< SHA1, with EMSA1 (IEEE1363-2000) encoding (this is the usual DSA algorithm - FIPS186)
77 EMSA3_SHA1, ///< SHA1, with EMSA3 (ie PKCS#1 Version 1.5) encoding
78 EMSA3_MD5, ///< MD5, with EMSA3 (ie PKCS#1 Version 1.5) encoding (this is the usual RSA algorithm)
79 EMSA3_MD2, ///< MD2, with EMSA3 (ie PKCS#1 Version 1.5) encoding
80 EMSA3_RIPEMD160, ///< RIPEMD160, with EMSA3 (ie PKCS#1 Version 1.5) encoding
81 EMSA3_Raw, ///< EMSA3 without computing a message digest or a DigestInfo encoding (identical to PKCS#11's
82 ///< CKM_RSA_PKCS mechanism)
83 EMSA3_SHA224, ///< SHA224, with EMSA3 (ie PKCS#1 Version 1.5) encoding
84 EMSA3_SHA256, ///< SHA256, with EMSA3 (ie PKCS#1 Version 1.5) encoding
85 EMSA3_SHA384, ///< SHA384, with EMSA3 (ie PKCS#1 Version 1.5) encoding
86 EMSA3_SHA512 ///< SHA512, with EMSA3 (ie PKCS#1 Version 1.5) encoding
87};
88
89/**
90 Signature formats (DSA only)
91*/
92enum SignatureFormat
93{
94 DefaultFormat, ///< For DSA, this is the same as IEEE_1363
95 IEEE_1363, ///< 40-byte format from IEEE 1363 (Botan/.NET)
96 DERSequence ///< Signature wrapped in DER formatting (OpenSSL/Java)
97};
98
99/**
100 Password-based encryption
101*/
102enum PBEAlgorithm
103{
104 PBEDefault, ///< Use modern default (same as PBES2_TripleDES_SHA1)
105 PBES2_DES_SHA1, ///< PKCS#5 v2.0 DES/CBC,SHA1
106 PBES2_TripleDES_SHA1, ///< PKCS#5 v2.0 TripleDES/CBC,SHA1
107 PBES2_AES128_SHA1, ///< PKCS#5 v2.0 AES-128/CBC,SHA1
108 PBES2_AES192_SHA1, ///< PKCS#5 v2.0 AES-192/CBC,SHA1
109 PBES2_AES256_SHA1 ///< PKCS#5 v2.0 AES-256/CBC,SHA1
110};
111
112/**
113 Return value from a format conversion
114
115 Note that if you are checking for any result other than ConvertGood,
116 then you may be introducing a provider specific dependency.
117*/
118enum ConvertResult
119{
120 ConvertGood, ///< Conversion succeeded, results should be valid
121 ErrorDecode, ///< General failure in the decode stage
122 ErrorPassphrase, ///< Failure because of incorrect passphrase
123 ErrorFile ///< Failure because of incorrect file
124};
125
126/**
127 Well known discrete logarithm group sets
128
129 These sets are derived from three main sources:
130 Java Cryptographic Extensions,
131 <a href="http://www.ietf.org/rfc/rfc2412.txt">RFC2412</a> and
132 <a href="http://www.ietf.org/rfc/rfc3526.txt">RFC3526</a>.
133*/
134enum DLGroupSet
135{
136 DSA_512, ///< 512 bit group, for compatibility with JCE
137 DSA_768, ///< 768 bit group, for compatibility with JCE
138 DSA_1024, ///< 1024 bit group, for compatibility with JCE
139 IETF_768, ///< Group 1 from RFC 2412, Section E.1
140 IETF_1024, ///< Group 2 from RFC 2412, Section E.2
141 IETF_1536, ///< 1536-bit MODP Group ("group 5") from RFC3526 Section 2.
142 IETF_2048, ///< 2048-bit MODP Group ("group 14") from RFC3526 Section 3.
143 IETF_3072, ///< 3072-bit MODP Group ("group 15") from RFC3526 Section 4.
144 IETF_4096, ///< 4096-bit MODP Group ("group 16") from RFC3526 Section 5.
145 IETF_6144, ///< 6144-bit MODP Group ("group 17") from RFC3526 Section 6.
146 IETF_8192 ///< 8192-bit MODP Group ("group 18") from RFC3526 Section 7.
147
148};
149
150/**
151 Encode a hash result in EMSA3 (PKCS#1) format
152
153 This is a convenience function for providers that only have access
154 to raw RSA signing (mainly smartcard providers). This is a built-in
155 function of QCA and does not utilize a provider. SHA1, MD5, MD2,
156 and RIPEMD160 are supported.
157
158 \param hashName the hash type used to create the digest
159 \param digest the digest to encode in EMSA3 format
160 \param size the desired size of the encoding output (-1 for automatic size)
161*/
162QCA_EXPORT QByteArray emsa3Encode(const QString &hashName, const QByteArray &digest, int size = -1);
163
164/**
165 \class DLGroup qca_publickey.h QtCrypto
166
167 A discrete logarithm group
168
169 \ingroup UserAPI
170*/
171class QCA_EXPORT DLGroup
172{
173public:
174 DLGroup();
175
176 /**
177 Construct a discrete logarithm group from raw parameters
178
179 \param p the P parameter
180 \param q the Q parameter
181 \param g the G parameter
182 */
183 DLGroup(const BigInteger &p, const BigInteger &q, const BigInteger &g);
184
185 /**
186 Construct a discrete logarithm group from raw parameters
187
188 \param p the P parameter
189 \param g the G parameter
190 */
191 DLGroup(const BigInteger &p, const BigInteger &g);
192
193 /**
194 Standard copy constructor
195
196 \param from the group to copy from
197 */
198 DLGroup(const DLGroup &from);
199 ~DLGroup();
200
201 /**
202 Standard assignment operator
203
204 \param from the DLGroup to copy from
205 */
206 DLGroup &operator=(const DLGroup &from);
207
208 /**
209 Provide a list of the supported group sets
210
211 \param provider the provider to report which group sets are
212 available. If not specified, all providers will be checked
213 */
214 static QList<DLGroupSet> supportedGroupSets(const QString &provider = QString());
215
216 /**
217 Test if the group is empty
218 */
219 bool isNull() const;
220
221 /**
222 Provide the p component of the group
223 */
224 BigInteger p() const;
225
226 /**
227 Provide the q component of the group
228 */
229 BigInteger q() const;
230
231 /**
232 Provide the g component of the group
233 */
234 BigInteger g() const;
235
236private:
237 class Private;
238 Private *d;
239};
240
241/**
242 \class PKey qca_publickey.h QtCrypto
243
244 General superclass for public (PublicKey) and private (PrivateKey) keys
245 used with asymmetric encryption techniques.
246
247 \ingroup UserAPI
248
249*/
250class QCA_EXPORT PKey : public Algorithm
251{
252public:
253 /**
254 Types of public key cryptography keys supported by QCA
255 */
256 enum Type
257 {
258 RSA, ///< RSA key
259 DSA, ///< DSA key
260 DH ///< Diffie Hellman key
261 };
262
263 /**
264 Standard constructor
265 */
266 PKey();
267
268 /**
269 Standard copy constructor
270
271 \param from the key to copy from
272 */
273 PKey(const PKey &from);
274
275 ~PKey() override;
276
277 /**
278 Standard assignment operator
279
280 \param from the PKey to copy from
281 */
282 PKey &operator=(const PKey &from);
283
284 /**
285 Test what types of keys are supported.
286
287 Normally you would just test if the capability is present, however
288 for PKey, you also need to test which types of keys are available.
289 So if you want to figure out if RSA keys are supported, you need to
290 do something like:
291 \code
292if(!QCA::isSupported("pkey") ||
293 !QCA::PKey::supportedTypes().contains(QCA::PKey::RSA))
294{
295 // then there is no RSA key support
296}
297else
298{
299 // there is RSA key support
300}
301 \endcode
302
303 To make things a bit more complex, supportedTypes() only
304 checks for basic functionality. If you want to check that
305 you can do operations with PEM or DER (eg toPEM(), fromPEM(), and
306 the equivalent DER and PEMfile operations, plus anything else
307 that uses them, including the constructor form that takes a
308 fileName), then you need to check for supportedIOTypes() instead.
309
310 \param provider the name of the provider to use, if a particular
311 provider is required.
312
313 \sa supportedIOTypes()
314 */
315 static QList<Type> supportedTypes(const QString &provider = QString());
316
317 /**
318 Test what types of keys are supported for IO operations
319
320 If you are using PKey DER or PEM operations, then you need
321 to check for appropriate support using this method. For example,
322 if you want to check if you can export or import an RSA key, then
323 you need to do something like:
324 \code
325if(!QCA::isSupported("pkey") ||
326 !QCA::PKey::supportedIOTypes().contains(QCA::PKey::RSA))
327{
328 // then there is no RSA key IO support
329}
330else
331{
332 // there is RSA key IO support
333}
334 \endcode
335
336 Note that if you only want to check for basic functionality
337 (ie not PEM or DER import/export), then you can use
338 supportedTypes(). There is no need to use both - if the key type
339 is supported for IO, then is also supported for basic operations.
340
341 \param provider the name of the provider to use, if a particular
342 provider is required.
343
344 \sa supportedTypes()
345 */
346 static QList<Type> supportedIOTypes(const QString &provider = QString());
347
348 /**
349 Test if the key is null (empty)
350
351 \return true if the key is null
352 */
353 bool isNull() const;
354
355 /**
356 Report the Type of key (eg RSA, DSA or Diffie Hellman)
357
358 \sa isRSA, isDSA and isDH for boolean tests.
359 */
360 Type type() const;
361
362 /**
363 Report the number of bits in the key
364 */
365 int bitSize() const;
366
367 /**
368 Test if the key is an RSA key
369 */
370 bool isRSA() const;
371
372 /**
373 Test if the key is a DSA key
374 */
375 bool isDSA() const;
376
377 /**
378 Test if the key is a Diffie Hellman key
379 */
380 bool isDH() const;
381
382 /**
383 Test if the key is a public key
384 */
385 bool isPublic() const;
386
387 /**
388 Test if the key is a private key
389 */
390 bool isPrivate() const;
391
392 /**
393 Test if the key data can be exported. If the key resides on a
394 smart card or other such device, this will likely return false.
395 */
396 bool canExport() const;
397
398 /**
399 Test if the key can be used for key agreement
400 */
401 bool canKeyAgree() const;
402
403 /**
404 Interpret this key as a PublicKey
405
406 \sa toRSAPublicKey(), toDSAPublicKey() and toDHPublicKey()
407 for protected forms of this call.
408 */
409 PublicKey toPublicKey() const;
410
411 /**
412 Interpret this key as a PrivateKey
413 */
414 PrivateKey toPrivateKey() const;
415
416 /**
417 test if two keys are equal
418
419 \param a the key to compare with this key
420 */
421 bool operator==(const PKey &a) const;
422
423 /**
424 test if two keys are not equal
425
426 \param a the key to compare with this key
427 */
428 bool operator!=(const PKey &a) const;
429
430protected:
431 /**
432 Create a key of the specified type
433
434 \param type the name of the type of key to create
435 \param provider the name of the provider to create the key in
436 */
437 PKey(const QString &type, const QString &provider);
438
439 /**
440 Set the key
441
442 \param k the key to assign from
443 */
444 void set(const PKey &k);
445
446 /**
447 Interpret this key as an RSAPublicKey
448
449 \note This function is essentially a convenience cast - if the
450 key was created as a DSA key, this function cannot turn it into
451 an RSA key.
452
453 \sa toPublicKey() for the public version of this method
454 */
455 RSAPublicKey toRSAPublicKey() const;
456
457 /**
458 Interpret this key as an RSAPrivateKey
459
460 \note This function is essentially a convenience cast - if the
461 key was created as a DSA key, this function cannot turn it into
462 a RSA key.
463
464 \sa toPrivateKey() for the public version of this method
465 */
466 RSAPrivateKey toRSAPrivateKey() const;
467
468 /**
469 Interpret this key as an DSAPublicKey
470
471 \note This function is essentially a convenience cast - if the
472 key was created as an RSA key, this function cannot turn it into
473 a DSA key.
474
475 \sa toPublicKey() for the public version of this method
476 */
477 DSAPublicKey toDSAPublicKey() const;
478
479 /**
480 Interpret this key as a DSAPrivateKey
481
482 \note This function is essentially a convenience cast - if the
483 key was created as an RSA key, this function cannot turn it into
484 a DSA key.
485
486 \sa toPrivateKey() for the public version of this method
487 */
488 DSAPrivateKey toDSAPrivateKey() const;
489
490 /**
491 Interpret this key as an DHPublicKey
492
493 \note This function is essentially a convenience cast - if the
494 key was created as a DSA key, this function cannot turn it into
495 a DH key.
496
497 \sa toPublicKey() for the public version of this method
498 */
499 DHPublicKey toDHPublicKey() const;
500
501 /**
502 Interpret this key as a DHPrivateKey
503
504 \note This function is essentially a convenience cast - if the
505 key was created as a DSA key, this function cannot turn it into
506 a DH key.
507
508 \sa toPrivateKey() for the public version of this method
509 */
510 DHPrivateKey toDHPrivateKey() const;
511
512private:
513 void assignToPublic(PKey *dest) const;
514 void assignToPrivate(PKey *dest) const;
515
516 class Private;
517 Private *d;
518};
519
520/**
521 \class PublicKey qca_publickey.h QtCrypto
522
523 Generic public key
524
525 \ingroup UserAPI
526
527*/
528class QCA_EXPORT PublicKey : public PKey
529{
530public:
531 /**
532 Create an empty (null) public key
533 */
534 PublicKey();
535
536 /**
537 Create a public key based on a specified private key
538
539 \param k the private key to extract the public key parts from
540 */
541 PublicKey(const PrivateKey &k);
542
543 /**
544 Import a public key from a PEM representation in a file
545
546 \param fileName the name of the file containing the public key
547
548 \sa fromPEMFile for an alternative method
549 */
550 PublicKey(const QString &fileName);
551
552 /**
553 Copy constructor
554
555 \param from the PublicKey to copy from
556 */
557 PublicKey(const PublicKey &from);
558
559 ~PublicKey() override;
560
561 /**
562 Assignment operator
563
564 \param from the PublicKey to copy from
565 */
566 PublicKey &operator=(const PublicKey &from);
567
568 /**
569 Convenience method to convert this key to an RSAPublicKey
570
571 Note that if the key is not an RSA key (eg it is DSA or DH),
572 then this will produce a null key.
573 */
574 RSAPublicKey toRSA() const;
575
576 /**
577 Convenience method to convert this key to a DSAPublicKey
578
579 Note that if the key is not an DSA key (eg it is RSA or DH),
580 then this will produce a null key.
581 */
582 DSAPublicKey toDSA() const;
583
584 /**
585 Convenience method to convert this key to a DHPublicKey
586
587 Note that if the key is not an DH key (eg it is DSA or RSA),
588 then this will produce a null key.
589 */
590 DHPublicKey toDH() const;
591
592 /**
593 Test if this key can be used for encryption
594
595 \return true if the key can be used for encryption
596 */
597 bool canEncrypt() const;
598
599 /**
600 Test if this key can be used for decryption
601
602 \return true if the key can be used for decryption
603 */
604 bool canDecrypt() const;
605
606 /**
607 Test if the key can be used for verifying signatures
608
609 \return true of the key can be used for verification
610 */
611 bool canVerify() const;
612
613 /**
614 The maximum message size that can be encrypted with a specified
615 algorithm
616
617 \param alg the algorithm to check
618 */
619 int maximumEncryptSize(EncryptionAlgorithm alg) const;
620
621 /**
622 Encrypt a message using a specified algorithm
623
624 \param a the message to encrypt
625 \param alg the algorithm to use
626 */
627 SecureArray encrypt(const SecureArray &a, EncryptionAlgorithm alg);
628
629 /**
630 Decrypt the message
631
632 \param in the cipher (encrypted) data
633 \param out the plain text data
634 \param alg the algorithm to use
635
636 \note This synchronous operation may require event handling, and so
637 it must not be called from the same thread as an EventHandler.
638 */
639 bool decrypt(const SecureArray &in, SecureArray *out, EncryptionAlgorithm alg);
640
641 /**
642 Initialise the signature verification process
643
644 \param alg the algorithm to use for signing
645 \param format the specific format to use, for DSA
646 */
647 void startVerify(SignatureAlgorithm alg, SignatureFormat format = DefaultFormat);
648
649 /**
650 Update the signature verification process with more data
651
652 \param a the array containing the data that should be added to the signature
653 */
654 void update(const MemoryRegion &a);
655
656 /**
657 Check the signature is valid for the message
658
659 The process to check that a signature is correct is shown below:
660 \code
661// note that pubkey is a PublicKey
662if( pubkey.canVerify() )
663{
664 pubkey.startVerify( QCA::EMSA3_MD5 );
665 pubkey.update( theMessage ); // might be called multiple times
666 if ( pubkey.validSignature( theSignature ) )
667 {
668 // then signature is valid
669 }
670 else
671 {
672 // then signature is invalid
673 }
674}
675 \endcode
676
677 \param sig the signature to check
678
679 \return true if the signature is correct
680 */
681 bool validSignature(const QByteArray &sig);
682
683 /**
684 Single step message verification
685
686 If you have the whole message to be verified, then this offers a
687 more convenient approach to verification.
688
689 \param a the message to check the signature on
690 \param sig the signature to be checked
691 \param alg the algorithm to use
692 \param format the signature format to use, for DSA
693
694 \return true if the signature is valid for the message
695 */
696 bool verifyMessage(const MemoryRegion &a,
697 const QByteArray &sig,
698 SignatureAlgorithm alg,
699 SignatureFormat format = DefaultFormat);
700
701 /**
702 Export the key in Distinguished Encoding Rules (DER) format
703 */
704 QByteArray toDER() const;
705
706 /**
707 Export the key in Privacy Enhanced Mail (PEM) format
708
709 \sa toPEMFile provides a convenient way to save the PEM encoded key
710 to a file
711 \sa fromPEM provides an inverse of toPEM, converting the PEM
712 encoded key back to a PublicKey
713 */
714 QString toPEM() const;
715
716 /**
717 Export the key in Privacy Enhanced Mail (PEM) to a file
718
719 \param fileName the name (and path, if necessary) of the file to
720 save the PEM encoded key to.
721
722 \sa toPEM for a version that exports to a QString, which may be
723 useful if you need to do more sophisticated handling
724 \sa fromPEMFile provides an inverse of toPEMFile, reading a PEM
725 encoded key from a file
726 */
727 bool toPEMFile(const QString &fileName) const;
728
729 /**
730 Import a key in Distinguished Encoding Rules (DER) format
731
732 This function takes a binary array, which is assumed to contain a
733 public key in DER encoding, and returns the key. Unless you don't
734 care whether the import succeeded, you should test the result, as
735 shown below.
736
737 \code
738QCA::ConvertResult conversionResult;
739QCA::PublicKey publicKey = QCA::PublicKey::fromDER(keyArray, &conversionResult);
740if (! QCA::ConvertGood == conversionResult)
741{
742 std::cout << "Public key read failed" << std::endl;
743}
744 \endcode
745
746 \param a the array containing a DER encoded key
747 \param result pointer to a variable, which returns whether the
748 conversion succeeded (ConvertGood) or not
749 \param provider the name of the provider to use for the import.
750 */
751 static PublicKey fromDER(const QByteArray &a, ConvertResult *result = nullptr, const QString &provider = QString());
752
753 /**
754 Import a key in Privacy Enhanced Mail (PEM) format
755
756 This function takes a string, which is assumed to contain a public
757 key in PEM encoding, and returns that key. Unless you don't care
758 whether the import succeeded, you should test the result, as shown
759 below.
760
761 \code
762QCA::ConvertResult conversionResult;
763QCA::PublicKey publicKey = QCA::PublicKey::fromPEM(keyAsString, &conversionResult);
764if (! QCA::ConvertGood == conversionResult)
765{
766 std::cout << "Public key read failed" << std::endl;
767}
768 \endcode
769
770 \param s the string containing a PEM encoded key
771 \param result pointer to a variable, which returns whether the
772 conversion succeeded (ConvertGood) or not
773 \param provider the name of the provider to use for the import.
774
775 \sa toPEM, which provides an inverse of fromPEM()
776 \sa fromPEMFile, which provides an import direct from a file.
777 */
778 static PublicKey fromPEM(const QString &s, ConvertResult *result = nullptr, const QString &provider = QString());
779
780 /**
781 Import a key in Privacy Enhanced Mail (PEM) format from a file
782
783 This function takes the name of a file, which is assumed to contain
784 a public key in PEM encoding, and returns that key. Unless you
785 don't care whether the import succeeded, you should test the
786 result, as shown below.
787
788 \code
789QCA::ConvertResult conversionResult;
790QCA::PublicKey publicKey = QCA::PublicKey::fromPEMFile(fileName, &conversionResult);
791if (! QCA::ConvertGood == conversionResult)
792{
793 std::cout << "Public key read failed" << std::endl;
794}
795 \endcode
796
797 \param fileName a string containing the name of the file
798 \param result pointer to a variable, which returns whether the
799 conversion succeeded (ConvertGood) or not
800 \param provider the name of the provider to use for the import.
801
802 \sa toPEMFile, which provides an inverse of fromPEMFile()
803 \sa fromPEM, which provides an import from a string
804
805 \note there is also a constructor form that can import from a file
806 */
807 static PublicKey
808 fromPEMFile(const QString &fileName, ConvertResult *result = nullptr, const QString &provider = QString());
809
810protected:
811 /**
812 Create a new key of a specified type
813
814 \param type the type of key to create
815 \param provider the provider to use, if required
816 */
817 PublicKey(const QString &type, const QString &provider);
818
819private:
820 class Private;
821 Private *d;
822};
823
824/**
825 \class PrivateKey qca_publickey.h QtCrypto
826
827 Generic private key
828
829 \ingroup UserAPI
830
831*/
832class QCA_EXPORT PrivateKey : public PKey
833{
834public:
835 /**
836 Create an empty private key
837 */
838 PrivateKey();
839
840 /**
841 Import a private key from a PEM representation in a file
842
843 \param fileName the name of the file containing the private key
844 \param passphrase the pass phrase for the private key
845
846 \sa fromPEMFile for an alternative method
847
848 \note This synchronous operation may require event handling, and so
849 it must not be called from the same thread as an EventHandler.
850 */
851 explicit PrivateKey(const QString &fileName, const SecureArray &passphrase = SecureArray());
852
853 /**
854 Copy constructor
855
856 \param from the PrivateKey to copy from
857 */
858 PrivateKey(const PrivateKey &from);
859
860 ~PrivateKey() override;
861
862 /**
863 Assignment operator
864
865 \param from the PrivateKey to copy from
866 */
867 PrivateKey &operator=(const PrivateKey &from);
868
869 /**
870 Interpret / convert the key to an RSA key
871 */
872 RSAPrivateKey toRSA() const;
873
874 /**
875 Interpret / convert the key to a DSA key
876 */
877 DSAPrivateKey toDSA() const;
878
879 /**
880 Interpret / convert the key to a Diffie-Hellman key
881 */
882 DHPrivateKey toDH() const;
883
884 /**
885 Test if this key can be used for decryption
886
887 \return true if the key can be used for decryption
888 */
889 bool canDecrypt() const;
890
891 /**
892 Test if this key can be used for encryption
893
894 \return true if the key can be used for encryption
895 */
896 bool canEncrypt() const;
897
898 /**
899 Test if this key can be used for signing
900
901 \return true if the key can be used to make a signature
902 */
903 bool canSign() const;
904
905 /**
906 The maximum message size that can be encrypted with a specified
907 algorithm
908
909 \param alg the algorithm to check
910 */
911 int maximumEncryptSize(EncryptionAlgorithm alg) const;
912
913 /**
914 Decrypt the message
915
916 \param in the cipher (encrypted) data
917 \param out the plain text data
918 \param alg the algorithm to use
919
920 \note This synchronous operation may require event handling, and so
921 it must not be called from the same thread as an EventHandler.
922 */
923 bool decrypt(const SecureArray &in, SecureArray *out, EncryptionAlgorithm alg);
924
925 /**
926 Encrypt a message using a specified algorithm
927
928 \param a the message to encrypt
929 \param alg the algorithm to use
930 */
931 SecureArray encrypt(const SecureArray &a, EncryptionAlgorithm alg);
932
933 /**
934 Initialise the message signature process
935
936 \param alg the algorithm to use for the message signature process
937 \param format the signature format to use, for DSA
938
939 \note This synchronous operation may require event handling, and so
940 it must not be called from the same thread as an EventHandler.
941 */
942 void startSign(SignatureAlgorithm alg, SignatureFormat format = DefaultFormat);
943
944 /**
945 Update the signature process
946
947 \param a the message to use to update the signature
948
949 \note This synchronous operation may require event handling, and so
950 it must not be called from the same thread as an EventHandler.
951 */
952 void update(const MemoryRegion &a);
953
954 /**
955 The resulting signature
956
957 \note This synchronous operation may require event handling, and so
958 it must not be called from the same thread as an EventHandler.
959 */
960 QByteArray signature();
961
962 /**
963 One step signature process
964
965 \param a the message to sign
966 \param alg the algorithm to use for the signature
967 \param format the signature format to use, for DSA
968
969 \return the signature
970
971 \note This synchronous operation may require event handling, and so
972 it must not be called from the same thread as an EventHandler.
973 */
974 QByteArray signMessage(const MemoryRegion &a, SignatureAlgorithm alg, SignatureFormat format = DefaultFormat);
975
976 /**
977 Derive a shared secret key from a public key
978
979 \param theirs the public key to derive from
980 */
981 SymmetricKey deriveKey(const PublicKey &theirs);
982
983 /**
984 List the supported Password Based Encryption Algorithms that can be
985 used to protect the key.
986
987 \param provider the provider to use, if a particular provider is
988 required
989 */
990 static QList<PBEAlgorithm> supportedPBEAlgorithms(const QString &provider = QString());
991
992 /**
993 Export the key in Distinguished Encoding Rules (DER) format
994
995 \param passphrase the pass phrase to use to protect the key
996 \param pbe the symmetric encryption algorithm to use to protect the
997 key
998
999 \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
1111protected:
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
1121private:
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*/
1137class QCA_EXPORT KeyGenerator : public QObject
1138{
1139 Q_OBJECT
1140public:
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
1251Q_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
1259private:
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*/
1275class QCA_EXPORT RSAPublicKey : public PublicKey
1276{
1277public:
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*/
1326class QCA_EXPORT RSAPrivateKey : public PrivateKey
1327{
1328public:
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*/
1394class QCA_EXPORT DSAPublicKey : public PublicKey
1395{
1396public:
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*/
1438class QCA_EXPORT DSAPrivateKey : public PrivateKey
1439{
1440public:
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*/
1481class QCA_EXPORT DHPublicKey : public PublicKey
1482{
1483public:
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*/
1525class QCA_EXPORT DHPrivateKey : public PrivateKey
1526{
1527public:
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
1563

source code of qca/include/QtCrypto/qca_publickey.h