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" ), algType: 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" ), algType: 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 | |