1 /* 2 * qca_basic.h - Qt Cryptographic Architecture 3 * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com> 4 * Copyright (C) 2004-2007 Brad Hards <bradh@frogmouth.net> 5 * Copyright (C) 2013-2016 Ivan Romanov <drizt@land.ru> 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with this library; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20 * 02110-1301 USA 21 * 22 */ 23 24 /** 25 \file qca_basic.h 26 27 Header file for classes for cryptographic primitives (basic operations). 28 29 \note You should not use this header directly from an 30 application. You should just use <tt> \#include \<QtCrypto> 31 </tt> instead. 32 */ 33 34 #ifndef QCA_BASIC_H 35 #define QCA_BASIC_H 36 37 #include "qca_core.h" 38 39 #include <QIODevice> 40 41 namespace QCA { 42 43 /** 44 \defgroup UserAPI QCA user API 45 46 This is the main set of QCA classes, intended for use 47 in standard applications. 48 */ 49 50 /** 51 \class Random qca_basic.h QtCrypto 52 53 Source of random numbers. 54 55 QCA provides a built in source of random numbers, which 56 can be accessed through this class. You can also use 57 an alternative random number source, by implementing 58 another provider. 59 60 The normal use of this class is expected to be through the 61 static members - randomChar(), randomInt() and randomArray(). 62 63 \ingroup UserAPI 64 */ 65 class QCA_EXPORT Random : public Algorithm 66 { 67 public: 68 /** 69 Standard Constructor 70 71 \param provider the name of the provider library for the random 72 number generation 73 */ 74 Random(const QString &provider = QString()); 75 76 /** 77 Copy constructor 78 79 \param from the %Random object to copy from 80 */ 81 Random(const Random &from); 82 83 ~Random() override; 84 85 /** 86 Assignment operator 87 88 \param from the %Random object to copy state from 89 */ 90 Random &operator=(const Random &from); 91 92 /** 93 Provide a random byte. 94 95 This method isn't normally required - you should use 96 the static randomChar() method instead. 97 98 \sa randomChar 99 */ 100 uchar nextByte(); 101 102 /** 103 Provide a specified number of random bytes. 104 105 This method isn't normally required - you should use 106 the static randomArray() method instead. 107 108 \param size the number of bytes to provide 109 110 \sa randomArray 111 */ 112 SecureArray nextBytes(int size); 113 114 /** 115 Provide a random character (byte) 116 117 This is the normal way of obtaining a single random char 118 (i.e. 8 bit byte), as shown below: 119 \code 120 myRandomChar = QCA::Random::randomChar(); 121 \endcode 122 123 If you need a number of bytes, perhaps randomArray() may be of use. 124 */ 125 static uchar randomChar(); 126 127 /** 128 Provide a random integer. 129 130 This is the normal way of obtaining a single random integer, 131 as shown below: 132 \code 133 myRandomInt = QCA::Random::randomInt(); 134 \endcode 135 */ 136 static int randomInt(); 137 138 /** 139 Provide a specified number of random bytes. 140 141 \code 142 // build a 30 byte secure array. 143 SecureArray arry = QCA::Random::randomArray(30); 144 \endcode 145 146 \param size the number of bytes to provide 147 */ 148 static SecureArray randomArray(int size); 149 150 private: 151 class Private; 152 Private *d; 153 }; 154 155 /** 156 \class Hash qca_basic.h QtCrypto 157 158 General class for hashing algorithms. 159 160 Hash is the class for the various hashing algorithms 161 within %QCA. SHA256, SHA1 or RIPEMD160 are recommended for 162 new applications, although MD2, MD4, MD5 or SHA0 may be 163 applicable (for interoperability reasons) for some 164 applications. 165 166 To perform a hash, you create a Hash object, call update() 167 with the data that needs to be hashed, and then call 168 final(), which returns a QByteArray of the hash result. An 169 example (using the SHA1 hash, with 1000 updates of a 1000 170 byte string) is shown below: 171 172 \code 173 if(!QCA::isSupported("sha1")) 174 printf("SHA1 not supported!\n"); 175 else 176 { 177 QByteArray fillerString; 178 fillerString.fill('a', 1000); 179 180 QCA::Hash shaHash("sha1"); 181 for (int i=0; i<1000; i++) 182 shaHash.update(fillerString); 183 QByteArray hashResult = shaHash.final(); 184 if ( "34aa973cd4c4daa4f61eeb2bdbad27316534016f" == QCA::arrayToHex(hashResult) ) 185 { 186 printf("big SHA1 is OK\n"); 187 } 188 else 189 { 190 printf("big SHA1 failed\n"); 191 } 192 } 193 \endcode 194 195 If you only have a simple hash requirement - a single 196 string that is fully available in memory at one time - then 197 you may be better off with one of the convenience 198 methods. So, for example, instead of creating a QCA::Hash 199 object, then doing a single update() and the final() call; 200 you could simply call QCA::Hash("algoName").hash() with the 201 data that you would otherwise have provided to the update() 202 call. 203 204 For more information on hashing algorithms, see \ref hashing. 205 206 \ingroup UserAPI 207 */ 208 class QCA_EXPORT Hash : public Algorithm, public BufferedComputation 209 { 210 public: 211 /** 212 Constructor 213 214 \param type label for the type of hash to be 215 created (for example, "sha1" or "md2") 216 \param provider the name of the provider plugin 217 for the subclass (eg "qca-ossl") 218 */ 219 explicit Hash(const QString &type, const QString &provider = QString()); 220 221 /** 222 Copy constructor 223 224 \param from the Hash object to copy from 225 */ 226 Hash(const Hash &from); 227 228 ~Hash() override; 229 230 /** 231 Assignment operator 232 233 \param from the Hash object to copy state from 234 */ 235 Hash &operator=(const Hash &from); 236 237 /** 238 Returns a list of all of the hash types available 239 240 \param provider the name of the provider to get a list from, if one 241 provider is required. If not specified, available hash types from all 242 providers will be returned. 243 */ 244 static QStringList supportedTypes(const QString &provider = QString()); 245 246 /** 247 Return the hash type 248 */ 249 QString type() const; 250 251 /** 252 Reset a hash, dumping all previous parts of the 253 message. 254 255 This method clears (or resets) the hash algorithm, 256 effectively undoing any previous update() 257 calls. You should use this call if you are re-using 258 a Hash sub-class object to calculate additional 259 hashes. 260 */ 261 void clear() override; 262 263 /** 264 Update a hash, adding more of the message contents 265 to the digest. The whole message needs to be added 266 using this method before you call final(). 267 268 If you find yourself only calling update() once, 269 you may be better off using a convenience method 270 such as hash() or hashToString() instead. 271 272 \param a the byte array to add to the hash 273 */ 274 void update(const MemoryRegion &a) override; 275 276 /** 277 \overload 278 279 \param a the QByteArray to add to the hash 280 */ 281 void update(const QByteArray &a); 282 283 /** 284 \overload 285 286 This method is provided to assist with code that 287 already exists, and is being ported to %QCA. You are 288 better off passing a SecureArray (as shown above) 289 if you are writing new code. 290 291 \param data pointer to a char array 292 \param len the length of the array. If not specified 293 (or specified as a negative number), the length will be 294 determined with strlen(), which may not be what you want 295 if the array contains a null (0x00) character. 296 */ 297 void update(const char *data, int len = -1); 298 299 /** 300 \overload 301 302 This allows you to read from a file or other 303 I/O device. Note that the device must be already 304 open for reading 305 306 \param file an I/O device 307 308 If you are trying to calculate the hash of 309 a whole file (and it isn't already open), you 310 might want to use code like this: 311 \code 312 QFile f( "file.dat" ); 313 if ( f.open( QIODevice::ReadOnly ) ) 314 { 315 QCA::Hash hashObj("sha1"); 316 hashObj.update( &f ); 317 QByteArray output = hashObj.final().toByteArray(); 318 } 319 \endcode 320 */ 321 void update(QIODevice *file); 322 323 /** 324 Finalises input and returns the hash result 325 326 After calling update() with the required data, the 327 hash results are finalised and produced. 328 329 Note that it is not possible to add further data (with 330 update()) after calling final(), because of the way 331 the hashing works - null bytes are inserted to pad 332 the results up to a fixed size. If you want to 333 reuse the Hash object, you should call clear() and 334 start to update() again. 335 */ 336 MemoryRegion final() override; 337 338 /** 339 %Hash a byte array, returning it as another 340 byte array 341 342 This is a convenience method that returns the 343 hash of a SecureArray. 344 345 \code 346 SecureArray sampleArray(3); 347 sampleArray.fill('a'); 348 SecureArray outputArray = QCA::Hash("md2")::hash(sampleArray); 349 \endcode 350 351 \param array the QByteArray to hash 352 353 If you need more flexibility (e.g. you are constructing 354 a large byte array object just to pass it to hash(), then 355 consider creating an Hash object, and then calling 356 update() and final(). 357 */ 358 MemoryRegion hash(const MemoryRegion &array); 359 360 /** 361 %Hash a byte array, returning it as a printable 362 string 363 364 This is a convenience method that returns the 365 hash of a SecureArray as a hexadecimal 366 representation encoded in a QString. 367 368 \param array the QByteArray to hash 369 370 If you need more flexibility, you can create a Hash 371 object, call Hash::update() as required, then call 372 Hash::final(), before using the static arrayToHex() method. 373 */ 374 QString hashToString(const MemoryRegion &array); 375 376 private: 377 class Private; 378 Private *d; 379 }; 380 381 /** 382 \page hashing Hashing Algorithms 383 384 There are a range of hashing algorithms available in 385 %QCA. Hashing algorithms are used with the Hash and 386 MessageAuthenticationCode classes. 387 388 The MD2 algorithm takes an arbitrary data stream, known as the 389 message and outputs a condensed 128 bit (16 byte) 390 representation of that data stream, known as the message 391 digest. This algorithm is considered slightly more secure than MD5, 392 but is more expensive to compute. Unless backward 393 compatibility or interoperability are considerations, you 394 are better off using the SHA1 or RIPEMD160 hashing algorithms. 395 For more information on %MD2, see B. Kalinski RFC1319 "The %MD2 396 Message-Digest Algorithm". The label for MD2 is "md2". 397 398 The MD4 algorithm takes an arbitrary data stream, known as the 399 message and outputs a condensed 128 bit (16 byte) 400 representation of that data stream, known as the message 401 digest. MD4 is not considered to be secure, based on 402 known attacks. It should only be used for applications where 403 collision attacks are not a consideration (for example, as 404 used in the rsync algorithm for fingerprinting blocks of 405 data). If a secure hash is required, you are better off using 406 the SHA1 or RIPEMD160 hashing algorithms. MD2 and MD5 are both 407 stronger 128 bit hashes. For more information on MD4, see 408 R. Rivest RFC1320 "The %MD4 Message-Digest Algorithm". The 409 label for MD4 is "md4". 410 411 The MD5 takes an arbitrary data stream, known as the message 412 and outputs a condensed 128 bit (16 byte) representation of 413 that data stream, known as the message digest. MD5 is not 414 considered to be secure, based on known attacks. It should 415 only be used for applications where collision attacks are not 416 a consideration. If a secure hash is required, you are better 417 off using the SHA1 or RIPEMD160 hashing algorithms. For more 418 information on MD5, see R. Rivest RFC1321 "The %MD5 419 Message-Digest Algorithm". The label for MD5 is "md5". 420 421 The RIPEMD160 algorithm takes an arbitrary data stream, known 422 as the message (up to \f$2^{64}\f$ bits in length) and outputs 423 a condensed 160 bit (20 byte) representation of that data 424 stream, known as the message digest. The RIPEMD160 algorithm 425 is considered secure in that it is considered computationally 426 infeasible to find the message that produced the message 427 digest. The label for RIPEMD160 is "ripemd160". 428 429 The SHA-0 algorithm is a 160 bit hashing function, no longer 430 recommended for new applications because of known (partial) 431 attacks against it. The label for SHA-0 is "sha0". 432 433 The SHA-1 algorithm takes an arbitrary data stream, known as 434 the message (up to \f$2^{64}\f$ bits in length) and outputs a 435 condensed 160 bit (20 byte) representation of that data 436 stream, known as the message digest. SHA-1 is considered 437 secure in that it is considered computationally infeasible to 438 find the message that produced the message digest. For more 439 information on the SHA-1 algorithm,, see Federal Information 440 Processing Standard Publication 180-2 "Specifications for the 441 Secure %Hash Standard", available from 442 http://csrc.nist.gov/publications/. The label for SHA-1 is 443 "sha1". 444 445 The SHA-224 algorithm takes an arbitrary data stream, known as 446 the message (up to \f$2^{64}\f$ bits in length) and outputs a 447 condensed 224 bit (28 byte) representation of that data 448 stream, known as the message digest. SHA-224 is a "cut down" 449 version of SHA-256, and you may be better off using SHA-256 in 450 new designs. The SHA-224 algorithm is considered secure in 451 that it is considered computationally infeasible to find the 452 message that produced the message digest. For more information 453 on SHA-224, see Federal Information Processing Standard 454 Publication 180-2 "Specifications for the Secure %Hash 455 Standard", with change notice 1, available from 456 http://csrc.nist.gov/publications/. The label for SHA-224 is 457 "sha224". 458 459 The SHA-256 algorithm takes an arbitrary data stream, known as 460 the message (up to \f$2^{64}\f$ bits in length) and outputs a 461 condensed 256 bit (32 byte) representation of that data 462 stream, known as the message digest. The SHA-256 algorithm is 463 considered secure in that it is considered computationally 464 infeasible to find the message that produced the message 465 digest. For more information on SHA-256, see Federal 466 Information Processing Standard Publication 180-2 467 "Specifications for the Secure %Hash Standard", available from 468 http://csrc.nist.gov/publications/. The label for SHA-256 is 469 "sha256". 470 471 The SHA-384 algorithm takes an arbitrary data stream, known as 472 the message (up to \f$2^{128}\f$ bits in length) and outputs a 473 condensed 384 bit (48 byte) representation of that data 474 stream, known as the message digest. The SHA-384 algorithm is 475 a "cut down" version of SHA-512, and you may be better off 476 using SHA-512 in new designs. The SHA-384 algorithm is 477 considered secure in that it is considered computationally 478 infeasible to find the message that produced the message 479 digest. For more information on SHA-384, see Federal 480 Information Processing Standard Publication 180-2 481 "Specifications for the Secure %Hash Standard", available from 482 http://csrc.nist.gov/publications/. The label for SHA-384 is 483 "sha384". 484 485 The SHA-512 algorithm takes an arbitrary data stream, known as 486 the message (up to \f$2^{128}\f$ bits in length) and outputs a 487 condensed 512 bit (64 byte) representation of that data 488 stream, known as the message digest. The SHA-512 algorithm is 489 considered secure in that it is considered computationally 490 infeasible to find the message that produced the message 491 digest. For more information on SHA-512, see Federal 492 Information Processing Standard Publication 180-2 493 "Specifications for the Secure %Hash Standard", available from 494 http://csrc.nist.gov/publications/. The label for SHA-512 is 495 "sha512". 496 497 The Whirlpool algorithm takes an arbitrary data stream, known as 498 the message (up to \f$2^{256}\f$ bits in length) and outputs a 499 condensed 512 bit (64 byte) representation of that data 500 stream, known as the message digest. The Whirlpool algorithm is 501 considered secure in that it is considered computationally 502 infeasible to find the message that produced the message 503 digest. For more information on Whirlpool, see 504 http://paginas.terra.com.br/informatica/paulobarreto/WhirlpoolPage.html 505 or ISO/IEC 10118-3:2004. The label for Whirlpool is 506 "whirlpool". 507 */ 508 509 /** 510 \page paddingDescription Padding 511 512 For those Cipher sub-classes that are block based, there are modes 513 that require a full block on encryption and decryption - %Cipher Block 514 Chaining mode and Electronic Code Book modes are good examples. 515 516 Since real world messages are not always a convenient multiple of a 517 block size, we have to adding <i>padding</i>. There are a number of 518 padding modes that %QCA supports, including not doing any padding 519 at all. 520 521 If you are not going to use padding, then you can pass 522 QCA::Cipher::NoPadding as the pad argument to the Cipher sub-class, 523 however it is then your responsibility to pass in appropriate data for 524 the mode that you are using. 525 526 The most common padding scheme is known as PKCS#7 (also PKCS#1), and 527 it specifies that the pad bytes are all equal to the length of the 528 padding ( for example, if you need three pad bytes to complete the block, 529 then the padding is 0x03 0x03 0x03 ). PKCS#5 padding is a subset of 530 PKCS#7 padding for 8 byte block sizes. For explanation, see 531 http://crypto.stackexchange.com/questions/9043/what-is-the-difference-between-pkcs5-padding-and-pkcs7-padding/9044#9044. 532 533 On encryption, for algorithm / mode combinations that require 534 padding, you will get a block of ciphertext when the input plain 535 text block is complete. When you call final(), you will get out the 536 ciphertext that corresponds to the last part of the plain text, 537 plus any padding. If you had provided plaintext that matched up 538 with a block size, then the cipher text block is generated from 539 pure padding - you always get at least some padding, to ensure that 540 the padding can be safely removed on decryption. 541 542 On decryption, for algorithm / mode combinations that use padding, 543 you will get back a block of plaintext when the input ciphertext block 544 is complete. When you call final(), you will get a block that has been 545 stripped of ciphertext. 546 */ 547 548 /** 549 \class Cipher qca_basic.h QtCrypto 550 551 General class for cipher (encryption / decryption) algorithms. 552 553 Cipher is the class for the various algorithms that perform 554 low level encryption and decryption within %QCA. 555 556 AES128, AES192 and AES256 are recommended for new applications. 557 558 Standard names for ciphers are: 559 - Blowfish - "blowfish" 560 - TripleDES - "tripledes" 561 - DES - "des" 562 - AES128 - "aes128" 563 - AES192 - "aes192" 564 - AES256 - "aes256" 565 - CAST5 (CAST-128) - "cast5" 566 567 When checking for the availability of a particular kind 568 of cipher operation (e.g. AES128 in CBC mode with PKCS7 569 padding), you append the mode and padding type (in that 570 example "aes128-cbc-pkcs7"). CFB and OFB modes don't use 571 padding, so they are always just the cipher name followed 572 by the mode (e.g. "blowfish-cfb" or "aes192-ofb"). If 573 you are not using padding with CBC mode (i.e. you are 574 ensuring block size operations yourself), just use 575 the cipher name followed by "-cbc" (e.g. "blowfish-cbc" 576 or "aes256-cbc"). 577 578 \ingroup UserAPI 579 */ 580 581 class QCA_EXPORT Cipher : public Algorithm, public Filter 582 { 583 public: 584 /** 585 Mode settings for cipher algorithms. 586 587 \note ECB is almost never what you want, unless you 588 are trying to implement a %Cipher variation that is not 589 supported by %QCA. 590 */ 591 enum Mode 592 { 593 CBC, ///< operate in %Cipher Block Chaining mode 594 CFB, ///< operate in %Cipher FeedBack mode 595 ECB, ///< operate in Electronic Code Book mode 596 OFB, ///< operate in Output FeedBack Mode 597 CTR, ///< operate in CounTer Mode 598 GCM, ///< operate in Galois Counter Mode 599 CCM ///< operate in Counter with CBC-MAC 600 }; 601 602 /** 603 Padding variations for cipher algorithms. 604 605 See the \ref paddingDescription description for more details on 606 padding schemes. 607 */ 608 enum Padding 609 { 610 DefaultPadding, ///< Default for cipher-mode 611 NoPadding, ///< Do not use padding 612 PKCS7 ///< Pad using the scheme in PKCS#7 613 }; 614 615 /** 616 Standard constructor 617 618 \param type the name of the cipher specialisation to use (e.g. 619 "aes128") 620 \param mode the operating Mode to use (e.g. QCA::Cipher::CBC) 621 \param pad the type of Padding to use 622 \param dir the Direction that this Cipher should use (Encode for 623 encryption, Decode for decryption) 624 \param key the SymmetricKey array that is the key 625 \param iv the InitializationVector to use (not used for ECB mode) 626 \param provider the name of the Provider to use 627 628 \note Padding only applies to CBC and ECB modes. CFB and OFB 629 ciphertext is always the length of the plaintext. 630 */ 631 Cipher(const QString & type, 632 Mode mode, 633 Padding pad = DefaultPadding, 634 Direction dir = Encode, 635 const SymmetricKey & key = SymmetricKey(), 636 const InitializationVector &iv = InitializationVector(), 637 const QString & provider = QString()); 638 639 /** 640 Standard constructor 641 642 \param type the name of the cipher specialisation to use (e.g. 643 "aes128") 644 \param mode the operating Mode to use (e.g. QCA::Cipher::CBC) 645 \param pad the type of Padding to use 646 \param dir the Direction that this Cipher should use (Encode for 647 encryption, Decode for decryption) 648 \param key the SymmetricKey array that is the key 649 \param iv the InitializationVector to use (not used for ECB mode) 650 \param tag the AuthTag to use (only for GCM and CCM modes) 651 \param provider the name of the Provider to use 652 653 \note Padding only applies to CBC and ECB modes. CFB and OFB 654 ciphertext is always the length of the plaintext. 655 */ 656 Cipher(const QString & type, 657 Mode mode, 658 Padding pad, 659 Direction dir, 660 const SymmetricKey & key, 661 const InitializationVector &iv, 662 const AuthTag & tag, 663 const QString & provider = QString()); 664 665 /** 666 Standard copy constructor 667 668 \param from the Cipher to copy state from 669 */ 670 Cipher(const Cipher &from); 671 672 ~Cipher() override; 673 674 /** 675 Assignment operator 676 677 \param from the Cipher to copy state from 678 */ 679 Cipher &operator=(const Cipher &from); 680 681 /** 682 Returns a list of all of the cipher types available 683 684 \param provider the name of the provider to get a list from, if one 685 provider is required. If not specified, available cipher types from all 686 providers will be returned. 687 */ 688 static QStringList supportedTypes(const QString &provider = QString()); 689 690 /** 691 Return the cipher type 692 */ 693 QString type() const; 694 695 /** 696 Return the cipher mode 697 */ 698 Mode mode() const; 699 700 /** 701 Return the cipher padding type 702 */ 703 Padding padding() const; 704 705 /** 706 Return the cipher direction 707 */ 708 Direction direction() const; 709 710 /** 711 Return acceptable key lengths 712 */ 713 KeyLength keyLength() const; 714 715 /** 716 Test if a key length is valid for the cipher algorithm 717 718 \param n the key length in bytes 719 \return true if the key would be valid for the current algorithm 720 */ 721 bool validKeyLength(int n) const; 722 723 /** 724 return the block size for the cipher object 725 */ 726 int blockSize() const; 727 728 /** 729 return the authentication tag for the cipher object 730 */ 731 AuthTag tag() const; 732 733 /** 734 reset the cipher object, to allow re-use 735 */ 736 void clear() override; 737 738 /** 739 pass in a byte array of data, which will be encrypted or decrypted 740 (according to the Direction that was set in the constructor or in 741 setup() ) and returned. 742 743 \param a the array of data to encrypt / decrypt 744 */ 745 MemoryRegion update(const MemoryRegion &a) override; 746 747 /** 748 complete the block of data, padding as required, and returning 749 the completed block 750 */ 751 MemoryRegion final() override; 752 753 /** 754 Test if an update() or final() call succeeded. 755 756 \return true if the previous call succeeded 757 */ 758 bool ok() const override; 759 760 /** 761 Reset / reconfigure the Cipher 762 763 You can use this to re-use an existing Cipher, rather than creating 764 a new object with a slightly different configuration. 765 766 \param dir the Direction that this Cipher should use (Encode for 767 encryption, Decode for decryption) 768 \param key the SymmetricKey array that is the key 769 \param iv the InitializationVector to use (not used for ECB Mode) 770 771 \note You should not leave iv empty for any Mode except ECB. 772 */ 773 void setup(Direction dir, const SymmetricKey &key, const InitializationVector &iv = InitializationVector()); 774 775 /** 776 Reset / reconfigure the Cipher 777 778 You can use this to re-use an existing Cipher, rather than creating 779 a new object with a slightly different configuration. 780 781 \param dir the Direction that this Cipher should use (Encode for 782 encryption, Decode for decryption) 783 \param key the SymmetricKey array that is the key 784 \param iv the InitializationVector to use (not used for ECB Mode) 785 \param tag the AuthTag to use (only for GCM and CCM modes) 786 787 \note You should not leave iv empty for any Mode except ECB. 788 */ 789 void setup(Direction dir, const SymmetricKey &key, const InitializationVector &iv, const AuthTag &tag); 790 791 /** 792 Construct a Cipher type string 793 794 \param cipherType the name of the algorithm (eg AES128, DES) 795 \param modeType the mode to operate the cipher in (eg QCA::CBC, 796 QCA::CFB) 797 \param paddingType the padding required (eg QCA::NoPadding, 798 QCA::PCKS7) 799 */ 800 static QString withAlgorithms(const QString &cipherType, Mode modeType, Padding paddingType); 801 802 private: 803 class Private; 804 Private *d; 805 }; 806 807 /** 808 \class MessageAuthenticationCode qca_basic.h QtCrypto 809 810 General class for message authentication code (MAC) algorithms. 811 812 MessageAuthenticationCode is a class for accessing the various 813 message authentication code algorithms within %QCA. 814 HMAC using SHA1 ("hmac(sha1)") or HMAC using SHA256 ("hmac(sha256)") 815 is recommended for new applications. 816 817 Note that if your application is potentially susceptable to "replay 818 attacks" where the message is sent more than once, you should include a 819 counter in the message that is covered by the MAC, and check that the 820 counter is always incremented every time you receive a message and MAC. 821 822 For more information on HMAC, see H. Krawczyk et al. RFC2104 823 "HMAC: Keyed-Hashing for Message Authentication" 824 825 \ingroup UserAPI 826 */ 827 class QCA_EXPORT MessageAuthenticationCode : public Algorithm, public BufferedComputation 828 { 829 public: 830 /** 831 Standard constructor 832 833 \param type the name of the MAC (and algorithm, if applicable) to 834 use 835 \param key the shared key 836 \param provider the provider to use, if a particular provider is 837 required 838 */ 839 MessageAuthenticationCode(const QString &type, const SymmetricKey &key, const QString &provider = QString()); 840 841 /** 842 Standard copy constructor 843 844 Copies the state (including key) from one MessageAuthenticationCode 845 to another 846 847 \param from the MessageAuthenticationCode to copy state from 848 */ 849 MessageAuthenticationCode(const MessageAuthenticationCode &from); 850 851 ~MessageAuthenticationCode() override; 852 853 /** 854 Assignment operator. 855 856 Copies the state (including key) from one MessageAuthenticationCode 857 to another 858 859 \param from the MessageAuthenticationCode to assign from. 860 */ 861 MessageAuthenticationCode &operator=(const MessageAuthenticationCode &from); 862 863 /** 864 Returns a list of all of the message authentication code types 865 available 866 867 \param provider the name of the provider to get a list from, if one 868 provider is required. If not specified, available message authentication 869 codes types from all providers will be returned. 870 */ 871 static QStringList supportedTypes(const QString &provider = QString()); 872 873 /** 874 Return the MAC type 875 */ 876 QString type() const; 877 878 /** 879 Return acceptable key lengths 880 */ 881 KeyLength keyLength() const; 882 883 /** 884 Test if a key length is valid for the MAC algorithm 885 886 \param n the key length in bytes 887 \return true if the key would be valid for the current algorithm 888 */ 889 bool validKeyLength(int n) const; 890 891 /** 892 Reset a MessageAuthenticationCode, dumping all 893 previous parts of the message. 894 895 This method clears (or resets) the algorithm, 896 effectively undoing any previous update() 897 calls. You should use this call if you are re-using 898 a %MessageAuthenticationCode sub-class object 899 to calculate additional MACs. Note that if the key 900 doesn't need to be changed, you don't need to call 901 setup() again, since the key can just be reused. 902 */ 903 void clear() override; 904 905 /** 906 Update the MAC, adding more of the message contents 907 to the digest. The whole message needs to be added 908 using this method before you call final(). 909 910 \param array the message contents 911 */ 912 void update(const MemoryRegion &array) override; 913 914 /** 915 Finalises input and returns the MAC result 916 917 After calling update() with the required data, the 918 hash results are finalised and produced. 919 920 Note that it is not possible to add further data (with 921 update()) after calling final(). If you want to 922 reuse the %MessageAuthenticationCode object, you 923 should call clear() and start to update() again. 924 */ 925 MemoryRegion final() override; 926 927 /** 928 Initialise the MAC algorithm 929 930 \param key the key to use for the algorithm 931 */ 932 void setup(const SymmetricKey &key); 933 934 private: 935 class Private; 936 Private *d; 937 }; 938 939 /** 940 \class KeyDerivationFunction qca_basic.h QtCrypto 941 942 General superclass for key derivation algorithms. 943 944 %KeyDerivationFunction is a superclass for the various 945 key derivation function algorithms within %QCA. You should 946 not need to use it directly unless you are 947 adding another key derivation capability to %QCA - you should be 948 using a sub-class. PBKDF2 using SHA1 is recommended for new applications. 949 950 \ingroup UserAPI 951 952 */ 953 class QCA_EXPORT KeyDerivationFunction : public Algorithm 954 { 955 public: 956 /** 957 Standard copy constructor 958 959 \param from the KeyDerivationFunction to copy from 960 */ 961 KeyDerivationFunction(const KeyDerivationFunction &from); 962 963 ~KeyDerivationFunction() override; 964 965 /** 966 Assignment operator 967 968 Copies the state (including key) from one KeyDerivationFunction 969 to another 970 971 \param from the KeyDerivationFunction to assign from 972 */ 973 KeyDerivationFunction &operator=(const KeyDerivationFunction &from); 974 975 /** 976 Generate the key from a specified secret and salt value 977 978 \note key length is ignored for some functions 979 980 \param secret the secret (password or passphrase) 981 \param salt the salt to use 982 \param keyLength the length of key to return 983 \param iterationCount the number of iterations to perform 984 985 \return the derived key 986 */ 987 SymmetricKey makeKey(const SecureArray & secret, 988 const InitializationVector &salt, 989 unsigned int keyLength, 990 unsigned int iterationCount); 991 992 /** 993 Generate the key from a specified secret and salt value 994 995 \note key length is ignored for some functions 996 997 \param secret the secret (password or passphrase) 998 \param salt the salt to use 999 \param keyLength the length of key to return 1000 \param msecInterval the maximum time to compute the key, in milliseconds 1001 \param iterationCount a pointer to store the number of iteration done for the specified time 1002 1003 \return the derived key 1004 */ 1005 SymmetricKey makeKey(const SecureArray & secret, 1006 const InitializationVector &salt, 1007 unsigned int keyLength, 1008 int msecInterval, 1009 unsigned int * iterationCount); 1010 1011 /** 1012 Construct the name of the algorithm 1013 1014 You can use this to build a standard name string. 1015 You probably only need this method if you are 1016 creating a new subclass. 1017 1018 \param kdfType the type of key derivation function 1019 \param algType the name of the algorithm to use with the key derivation function 1020 1021 \return the name of the KDF/algorithm pair 1022 */ 1023 static QString withAlgorithm(const QString &kdfType, const QString &algType); 1024 1025 protected: 1026 /** 1027 Special constructor for subclass initialisation 1028 1029 \param type the algorithm to create 1030 \param provider the name of the provider to create the key derivation function in. 1031 */ 1032 KeyDerivationFunction(const QString &type, const QString &provider); 1033 1034 private: 1035 class Private; 1036 Private *d; 1037 }; 1038 1039 /** 1040 \class PBKDF1 qca_basic.h QtCrypto 1041 1042 Password based key derivation function version 1 1043 1044 This class implements Password Based Key Derivation Function version 1, 1045 as specified in RFC2898, and also in PKCS#5. 1046 1047 \ingroup UserAPI 1048 */ 1049 class QCA_EXPORT PBKDF1 : public KeyDerivationFunction 1050 { 1051 public: 1052 /** 1053 Standard constructor 1054 1055 \param algorithm the name of the hashing algorithm to use 1056 \param provider the name of the provider to use, if available 1057 */ 1058 explicit PBKDF1(const QString &algorithm = QStringLiteral("sha1"), const QString &provider = QString()) 1059 : KeyDerivationFunction(withAlgorithm(QStringLiteral("pbkdf1"), algorithm), provider) 1060 { 1061 } 1062 }; 1063 1064 /** 1065 \class PBKDF2 qca_basic.h QtCrypto 1066 1067 Password based key derivation function version 2 1068 1069 This class implements Password Based Key Derivation Function version 2, 1070 as specified in RFC2898, and also in PKCS#5. 1071 1072 \ingroup UserAPI 1073 */ 1074 class QCA_EXPORT PBKDF2 : public KeyDerivationFunction 1075 { 1076 public: 1077 /** 1078 Standard constructor 1079 1080 \param algorithm the name of the hashing algorithm to use 1081 \param provider the name of the provider to use, if available 1082 */ 1083 explicit PBKDF2(const QString &algorithm = QStringLiteral("sha1"), const QString &provider = QString()) 1084 : KeyDerivationFunction(withAlgorithm(QStringLiteral("pbkdf2"), algorithm), provider) 1085 { 1086 } 1087 }; 1088 1089 /** 1090 \class HKDF qca_basic.h QtCrypto 1091 \since 2.3 1092 1093 HMAC-based extract-and-expand key derivation function 1094 1095 This class implements HMAC-based Extract-and-Expand Key Derivation Function, 1096 as specified in RFC5869. 1097 1098 \ingroup UserAPI 1099 */ 1100 class QCA_EXPORT HKDF : public Algorithm 1101 { 1102 public: 1103 /** 1104 Standard constructor 1105 1106 \param algorithm the name of the hashing algorithm to use 1107 \param provider the name of the provider to use, if available 1108 */ 1109 explicit HKDF(const QString &algorithm = QStringLiteral("sha256"), const QString &provider = QString()); 1110 1111 /** 1112 Standard copy constructor 1113 1114 \param from the KeyDerivationFunction to copy from 1115 */ 1116 HKDF(const HKDF &from); 1117 1118 ~HKDF() override; 1119 1120 /** 1121 Assignment operator 1122 1123 Copies the state (including key) from one HKDF 1124 to another 1125 1126 \param from the HKDF to assign from 1127 */ 1128 HKDF &operator=(const HKDF &from); 1129 1130 /** 1131 Generate the key from a specified secret, salt value, and an additional info 1132 1133 \note key length is ignored for some functions 1134 1135 \param secret the secret (password or passphrase) 1136 \param salt the salt to use 1137 \param info the info to use 1138 \param keyLength the length of key to return 1139 1140 \return the derived key 1141 */ 1142 SymmetricKey makeKey(const SecureArray & secret, 1143 const InitializationVector &salt, 1144 const InitializationVector &info, 1145 unsigned int keyLength); 1146 }; 1147 1148 } 1149 1150 #endif 1151