1 | /* |
2 | * qca_securelayer.h - Qt Cryptographic Architecture |
3 | * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com> |
4 | * Copyright (C) 2004-2006 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_securelayer.h |
25 | |
26 | Header file for SecureLayer and its subclasses |
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 | #ifndef QCA_SECURELAYER_H |
33 | #define QCA_SECURELAYER_H |
34 | |
35 | #include "qca_cert.h" |
36 | #include "qca_core.h" |
37 | #include "qca_publickey.h" |
38 | #include <QObject> |
39 | |
40 | namespace QCA { |
41 | |
42 | /** |
43 | Specify the lower-bound for acceptable TLS/SASL security layers |
44 | |
45 | For TLS, the interpretation of these levels is: |
46 | - Any cipher suite that provides non-authenticated communications |
47 | (usually anonymous Diffie-Hellman) is SL_Integrity. |
48 | - Any cipher suite that is limited to 40 bits (export-version |
49 | crippled forms of RC2, RC4 or DES) is SL_Export. Standard |
50 | DES (56 bits) and some forms of RC4 (64 bits) are also SL_Export. |
51 | - Any normal cipher (AES, Camellia, RC4 or similar) with 128 bits, or |
52 | Elliptic Curve Ciphers with 283 bits, is SL_Baseline |
53 | - AES or Camellia at least 192 bits, triple-DES and similar |
54 | ciphers are SL_High. ECC with 409 or more bits is also SL_High. |
55 | - Highest does not have an equivalent strength. It |
56 | indicates that the provider should use the strongest |
57 | ciphers available (but not less than SL_High). |
58 | */ |
59 | enum SecurityLevel |
60 | { |
61 | SL_None, ///< indicates that no security is ok |
62 | SL_Integrity, ///< must at least get integrity protection |
63 | SL_Export, ///< must be export level bits or more |
64 | SL_Baseline, ///< must be 128 bit or more |
65 | SL_High, ///< must be more than 128 bit |
66 | SL_Highest ///< SL_High or max possible, whichever is greater |
67 | }; |
68 | |
69 | /** |
70 | \class SecureLayer qca_securelayer.h QtCrypto |
71 | |
72 | Abstract interface to a security layer |
73 | |
74 | SecureLayer is normally used between an application and a |
75 | potentially insecure network. It provides secure |
76 | communications over that network. |
77 | |
78 | The concept is that (after some initial setup), the |
79 | application can write() some data to the SecureLayer |
80 | implementation, and that data is encrypted (or otherwise |
81 | protected, depending on the setup). The SecureLayer |
82 | implementation then emits the readyReadOutgoing() signal, |
83 | and the application uses readOutgoing() to retrieve the |
84 | encrypted data from the SecureLayer implementation. The |
85 | encrypted data is then sent out on the network. |
86 | |
87 | When some encrypted data comes back from the network, the |
88 | application does a writeIncoming() to the SecureLayer |
89 | implementation. Some time later, the SecureLayer |
90 | implementation may emit readyRead() to the application, |
91 | which then read()s the decrypted data from the SecureLayer |
92 | implementation. |
93 | |
94 | Note that sometimes data is sent or received between the |
95 | SecureLayer implementation and the network without any data |
96 | being sent between the application and the SecureLayer |
97 | implementation. This is a result of the initial negotiation |
98 | activities (which require network traffic to agree a |
99 | configuration to use) and other overheads associated with |
100 | the secure link. |
101 | |
102 | \ingroup UserAPI |
103 | */ |
104 | class QCA_EXPORT SecureLayer : public QObject |
105 | { |
106 | Q_OBJECT |
107 | public: |
108 | /** |
109 | Constructor for an abstract secure communications |
110 | layer |
111 | |
112 | \param parent the parent object for this object |
113 | */ |
114 | SecureLayer(QObject *parent = nullptr); |
115 | |
116 | /** |
117 | Returns true if the layer has a meaningful "close". |
118 | */ |
119 | virtual bool isClosable() const; |
120 | |
121 | /** |
122 | Returns the number of bytes available to be read() |
123 | on the application side. |
124 | */ |
125 | virtual int bytesAvailable() const = 0; |
126 | |
127 | /** |
128 | Returns the number of bytes available to be |
129 | readOutgoing() on the network side. |
130 | */ |
131 | virtual int bytesOutgoingAvailable() const = 0; |
132 | |
133 | /** |
134 | Close the link. Note that this may not be |
135 | meaningful / possible for all implementations. |
136 | |
137 | \sa isClosable() for a test that verifies if the |
138 | link can be %closed. |
139 | */ |
140 | virtual void close(); |
141 | |
142 | /** |
143 | This method writes unencrypted (plain) data to |
144 | the SecureLayer implementation. You normally |
145 | call this function on the application side. |
146 | |
147 | \param a the source of the application-side data |
148 | */ |
149 | virtual void write(const QByteArray &a) = 0; |
150 | |
151 | /** |
152 | This method reads decrypted (plain) data from |
153 | the SecureLayer implementation. You normally call |
154 | this function on the application side after receiving |
155 | the readyRead() signal. |
156 | */ |
157 | virtual QByteArray read() = 0; |
158 | |
159 | /** |
160 | This method accepts encoded (typically encrypted) data |
161 | for processing. You normally call this function using |
162 | data read from the network socket (e.g. using |
163 | QTcpSocket::readAll()) after receiving a signal that |
164 | indicates that the socket has data to read. |
165 | |
166 | \param a the ByteArray to take network-side data from |
167 | */ |
168 | virtual void writeIncoming(const QByteArray &a) = 0; |
169 | |
170 | /** |
171 | This method provides encoded (typically encrypted) |
172 | data. You normally call this function to get data |
173 | to write out to the network socket (e.g. using |
174 | QTcpSocket::write()) after receiving the |
175 | readyReadOutgoing() signal. |
176 | |
177 | \param plainBytes the number of bytes that were read. |
178 | */ |
179 | virtual QByteArray readOutgoing(int *plainBytes = nullptr) = 0; |
180 | |
181 | /** |
182 | This allows you to read data without having it |
183 | decrypted first. This is intended to be used for |
184 | protocols that close off the connection and return |
185 | to plain text transfer. You do not normally need to |
186 | use this function. |
187 | */ |
188 | virtual QByteArray readUnprocessed(); |
189 | |
190 | /** |
191 | Convert encrypted bytes written to plain text bytes written |
192 | |
193 | \param encryptedBytes the number of bytes to convert |
194 | */ |
195 | virtual int convertBytesWritten(qint64 encryptedBytes) = 0; |
196 | |
197 | Q_SIGNALS: |
198 | /** |
199 | This signal is emitted when SecureLayer has |
200 | decrypted (application side) data ready to be |
201 | read. Typically you will connect this signal to a |
202 | slot that reads the data (using read()). |
203 | */ |
204 | void readyRead(); |
205 | |
206 | /** |
207 | This signal is emitted when SecureLayer has encrypted |
208 | (network side) data ready to be read. Typically you |
209 | will connect this signal to a slot that reads the data |
210 | (using readOutgoing()) and writes it to a network socket. |
211 | */ |
212 | void readyReadOutgoing(); |
213 | |
214 | /** |
215 | This signal is emitted when the SecureLayer connection |
216 | is %closed. |
217 | */ |
218 | void closed(); |
219 | |
220 | /** |
221 | This signal is emitted when an error is detected. You |
222 | can determine the error type using errorCode(). |
223 | */ |
224 | void error(); |
225 | |
226 | private: |
227 | Q_DISABLE_COPY(SecureLayer) |
228 | }; |
229 | |
230 | /** |
231 | \class TLSSession qca_securelayer.h QtCrypto |
232 | |
233 | Session token, used for TLS resuming |
234 | |
235 | \ingroup UserAPI |
236 | |
237 | */ |
238 | class QCA_EXPORT TLSSession : public Algorithm |
239 | { |
240 | public: |
241 | TLSSession(); |
242 | |
243 | /** |
244 | Copy constructor |
245 | |
246 | \param from the session token to copy from |
247 | */ |
248 | TLSSession(const TLSSession &from); |
249 | |
250 | ~TLSSession() override; |
251 | |
252 | /** |
253 | Assignment operator |
254 | |
255 | \param from the session token to assign from |
256 | */ |
257 | TLSSession &operator=(const TLSSession &from); |
258 | |
259 | /** |
260 | Test if the session token is valid |
261 | */ |
262 | bool isNull() const; |
263 | }; |
264 | |
265 | /** |
266 | \class TLS qca_securelayer.h QtCrypto |
267 | |
268 | Transport Layer Security / Secure Socket Layer |
269 | |
270 | Transport Layer Security (%TLS) is the current |
271 | state-of-the-art in secure transport mechanisms over the |
272 | internet. It can be used in a way where only one side of |
273 | the link needs to authenticate to the other. This makes it |
274 | very useful for servers to provide their identity to |
275 | clients. Note that is is possible to use %TLS to |
276 | authenticate both client and server. |
277 | |
278 | %TLS is a IETF standard (<a |
279 | href="http://www.ietf.org/rfc/rfc2712.txt">RFC2712</a> for |
280 | TLS version 1.0, and <a |
281 | href="http://www.ietf.org/rfc/rfc4346.txt">RFC4346</a> for |
282 | TLS version 1.1) based on earlier Netscape work on Secure |
283 | Socket Layer (SSL version 2 and SSL version 3). New |
284 | applications should use at least TLS 1.0, and SSL version 2 |
285 | should be avoided due to known security problems. |
286 | |
287 | \ingroup UserAPI |
288 | */ |
289 | class QCA_EXPORT TLS : public SecureLayer, public Algorithm |
290 | { |
291 | Q_OBJECT |
292 | public: |
293 | /** |
294 | Operating mode |
295 | */ |
296 | enum Mode |
297 | { |
298 | Stream, ///< stream mode |
299 | Datagram ///< datagram mode |
300 | }; |
301 | |
302 | /** |
303 | Version of %TLS or SSL |
304 | */ |
305 | enum Version |
306 | { |
307 | TLS_v1, ///< Transport Layer Security, version 1 |
308 | SSL_v3, ///< Secure Socket Layer, version 3 |
309 | SSL_v2, ///< Secure Socket Layer, version 2 |
310 | DTLS_v1 ///< Datagram Transport Layer Security, version 1 |
311 | }; |
312 | |
313 | /** |
314 | Type of error |
315 | */ |
316 | enum Error |
317 | { |
318 | ErrorSignerExpired, ///< local certificate is expired |
319 | ErrorSignerInvalid, ///< local certificate is invalid in some way |
320 | ErrorCertKeyMismatch, ///< certificate and private key don't match |
321 | ErrorInit, ///< problem starting up %TLS |
322 | ErrorHandshake, ///< problem during the negotiation |
323 | ErrorCrypt ///< problem at anytime after |
324 | }; |
325 | |
326 | /** |
327 | Type of identity |
328 | */ |
329 | enum IdentityResult |
330 | { |
331 | Valid, ///< identity is verified |
332 | HostMismatch, ///< valid cert provided, but wrong owner |
333 | InvalidCertificate, ///< invalid cert |
334 | NoCertificate ///< identity unknown |
335 | }; |
336 | |
337 | /** |
338 | Constructor for Transport Layer Security connection |
339 | |
340 | This produces a Stream (normal %TLS) rather than Datagram (DTLS) |
341 | object. |
342 | If you want to do DTLS, see below. |
343 | |
344 | \param parent the parent object for this object |
345 | \param provider the name of the provider, if a specific provider |
346 | is required |
347 | */ |
348 | explicit TLS(QObject *parent = nullptr, const QString &provider = QString()); |
349 | |
350 | /** |
351 | Constructor for Transport Layer Security connection. |
352 | |
353 | This constructor can be used for both normal %TLS (set mode to TLS::Stream) |
354 | or DTLS (set mode to TLS::Datagram). |
355 | |
356 | \param mode the connection Mode |
357 | \param parent the parent object for this object |
358 | \param provider the name of the provider, if a specific provider is |
359 | required |
360 | */ |
361 | explicit TLS(Mode mode, QObject *parent = nullptr, const QString &provider = QString()); |
362 | |
363 | /** |
364 | Destructor |
365 | */ |
366 | ~TLS() override; |
367 | |
368 | /** |
369 | Reset the connection |
370 | */ |
371 | void reset(); |
372 | |
373 | /** |
374 | Get the list of cipher suites that are available for use. |
375 | |
376 | A cipher suite is a combination of key exchange, |
377 | encryption and hashing algorithms that are agreed |
378 | during the initial handshake between client and |
379 | server. |
380 | |
381 | \param version the protocol Version that the cipher |
382 | suites are required for |
383 | |
384 | \return list of the names of the cipher suites |
385 | supported. |
386 | */ |
387 | QStringList supportedCipherSuites(const Version &version = TLS_v1) const; |
388 | |
389 | /** |
390 | The local certificate to use. This is the |
391 | certificate that will be provided to the peer. This |
392 | is almost always required on the server side |
393 | (because the server has to provide a certificate to |
394 | the client), and may be used on the client side. |
395 | |
396 | \param cert a chain of certificates that |
397 | link the host certificate to a trusted root |
398 | certificate. |
399 | \param key the private key for the certificate |
400 | chain |
401 | */ |
402 | void setCertificate(const CertificateChain &cert, const PrivateKey &key); |
403 | |
404 | /** |
405 | \overload |
406 | |
407 | Allows setting a certificate from a KeyBundle. |
408 | |
409 | \param kb key bundle containing the local certificate |
410 | and associated private key. |
411 | */ |
412 | void setCertificate(const KeyBundle &kb); |
413 | |
414 | /** |
415 | Return the trusted certificates set for this object |
416 | */ |
417 | CertificateCollection trustedCertificates() const; |
418 | |
419 | /** |
420 | Set up the set of trusted certificates that will be used to verify |
421 | that the certificate provided is valid. |
422 | |
423 | Typically, this will be the collection of root certificates from |
424 | the system, which you can get using QCA::systemStore(), however you |
425 | may choose to pass whatever certificates match your assurance |
426 | needs. |
427 | |
428 | \param trusted a bundle of trusted certificates. |
429 | */ |
430 | void setTrustedCertificates(const CertificateCollection &trusted); |
431 | |
432 | /** |
433 | The security level required for this link |
434 | |
435 | \param s the level required for this link. |
436 | */ |
437 | void setConstraints(SecurityLevel s); |
438 | |
439 | /** |
440 | \overload |
441 | |
442 | \param minSSF the minimum Security Strength Factor |
443 | required for this link. |
444 | \param maxSSF the maximum Security Strength Factor |
445 | required for this link. |
446 | */ |
447 | void setConstraints(int minSSF, int maxSSF); |
448 | |
449 | /** |
450 | \overload |
451 | |
452 | \param cipherSuiteList a list of the names of |
453 | cipher suites that can be used for this link. |
454 | |
455 | \note the names are the same as the names in the |
456 | applicable IETF RFCs (or Internet Drafts if there |
457 | is no applicable RFC). |
458 | */ |
459 | void setConstraints(const QStringList &cipherSuiteList); |
460 | |
461 | /** |
462 | Retrieve the list of allowed issuers by the server, |
463 | if the server has provided them. Only DN types will |
464 | be present. |
465 | |
466 | \code |
467 | Certificate someCert = ... |
468 | PrivateKey someKey = ... |
469 | |
470 | // see if the server will take our cert |
471 | CertificateInfoOrdered issuerInfo = someCert.issuerInfoOrdered().dnOnly(); |
472 | foreach(const CertificateInfoOrdered &info, tls->issuerList()) |
473 | { |
474 | if(info == issuerInfo) |
475 | { |
476 | // server will accept someCert, let's present it |
477 | tls->setCertificate(someCert, someKey); |
478 | break; |
479 | } |
480 | } |
481 | \endcode |
482 | */ |
483 | QList<CertificateInfoOrdered> issuerList() const; |
484 | |
485 | /** |
486 | Sets the issuer list to present to the client. For |
487 | use with servers only. Only DN types are allowed. |
488 | |
489 | \param issuers the list of valid issuers to be used. |
490 | */ |
491 | void setIssuerList(const QList<CertificateInfoOrdered> &issuers); |
492 | |
493 | /** |
494 | Resume a %TLS session using the given session object |
495 | |
496 | \param session the session state to use for resumption. |
497 | */ |
498 | void setSession(const TLSSession &session); |
499 | |
500 | /** |
501 | Test if the link can use compression |
502 | |
503 | \return true if the link can use compression |
504 | */ |
505 | bool canCompress() const; |
506 | |
507 | /** |
508 | Test if the link can specify a hostname (Server Name |
509 | Indication) |
510 | |
511 | \return true if the link can specify a hostname |
512 | */ |
513 | bool canSetHostName() const; |
514 | |
515 | /** |
516 | Returns true if compression is enabled |
517 | |
518 | This only indicates whether or not the object is configured to use |
519 | compression, not whether or not the link is actually compressed. |
520 | Use isCompressed() for that. |
521 | */ |
522 | bool compressionEnabled() const; |
523 | |
524 | /** |
525 | Set the link to use compression |
526 | |
527 | \param b true if the link should use compression, or false to |
528 | disable compression |
529 | */ |
530 | void setCompressionEnabled(bool b); |
531 | |
532 | /** |
533 | Returns the host name specified or an empty string if no host |
534 | name is specified. |
535 | */ |
536 | QString hostName() const; |
537 | |
538 | /** |
539 | Start the %TLS/SSL connection as a client |
540 | |
541 | Typically, you'll want to perform RFC 2818 validation on the |
542 | server's certificate, based on the hostname you're intending |
543 | to connect to. Pass a value for \a host in order to have the |
544 | validation for you. If you want to bypass this behavior and |
545 | do the validation yourself, pass an empty string for \a host. |
546 | |
547 | If the host is an internationalized domain name, then it must be |
548 | provided in unicode format, not in IDNA ACE/punycode format. |
549 | |
550 | \param host the hostname that you want to connect to |
551 | |
552 | \note The hostname will be used for Server Name Indication |
553 | extension (see |
554 | <a href="http://www.ietf.org/rfc/rfc3546.txt">RFC 3546</a> Section |
555 | 3.1) if supported by the backend provider. |
556 | */ |
557 | void startClient(const QString &host = QString()); |
558 | |
559 | /** |
560 | Start the %TLS/SSL connection as a server. |
561 | */ |
562 | void startServer(); |
563 | |
564 | /** |
565 | Resumes %TLS processing. |
566 | |
567 | Call this function after hostNameReceived(), certificateRequested() |
568 | peerCertificateAvailable() or handshaken() is emitted. By |
569 | requiring this function to be called in order to proceed, |
570 | applications are given a chance to perform user interaction between |
571 | steps in the %TLS process. |
572 | */ |
573 | void continueAfterStep(); |
574 | |
575 | /** |
576 | test if the handshake is complete |
577 | |
578 | \return true if the handshake is complete |
579 | |
580 | \sa handshaken |
581 | */ |
582 | bool isHandshaken() const; |
583 | |
584 | /** |
585 | test if the link is compressed |
586 | |
587 | \return true if the link is compressed |
588 | */ |
589 | bool isCompressed() const; |
590 | |
591 | /** |
592 | The protocol version that is in use for this connection. |
593 | */ |
594 | Version version() const; |
595 | |
596 | /** |
597 | The cipher suite that has been negotiated for this connection. |
598 | |
599 | The name returned here is the name used in the applicable RFC |
600 | (or Internet Draft, where there is no RFC). |
601 | */ |
602 | QString cipherSuite() const; |
603 | |
604 | /** |
605 | The number of effective bits of security being used for this |
606 | connection. |
607 | |
608 | This can differ from the actual number of bits in |
609 | the cipher for certain |
610 | older "export ciphers" that are deliberately crippled. If you |
611 | want that information, use cipherMaxBits(). |
612 | */ |
613 | int cipherBits() const; |
614 | |
615 | /** |
616 | The number of bits of security that the cipher could use. |
617 | |
618 | This is normally the same as cipherBits(), but can be greater |
619 | for older "export ciphers". |
620 | */ |
621 | int cipherMaxBits() const; |
622 | |
623 | /** |
624 | The session object of the %TLS connection, which can be used |
625 | for resuming. |
626 | */ |
627 | TLSSession session() const; |
628 | |
629 | /** |
630 | This method returns the type of error that has |
631 | occurred. You should only need to check this if the |
632 | error() signal is emitted. |
633 | */ |
634 | Error errorCode() const; |
635 | |
636 | /** |
637 | After the SSL/%TLS handshake is complete, this |
638 | method allows you to determine if the other end |
639 | of the connection (if the application is a client, |
640 | this is the server; if the application is a server, |
641 | this is the client) has a valid identity. |
642 | |
643 | Note that the security of %TLS/SSL depends on |
644 | checking this. It is not enough to check that the |
645 | certificate is valid - you must check that the |
646 | certificate is valid for the entity that you are |
647 | trying to communicate with. |
648 | |
649 | \note If this returns QCA::TLS::InvalidCertificate, |
650 | you may wish to use peerCertificateValidity() to |
651 | determine whether to proceed or not. |
652 | */ |
653 | IdentityResult peerIdentityResult() const; |
654 | |
655 | /** |
656 | After the SSL/%TLS handshake is valid, this method |
657 | allows you to check if the received certificate |
658 | from the other end is valid. As noted in |
659 | peerIdentityResult(), you also need to check that |
660 | the certificate matches the entity you are trying |
661 | to communicate with. |
662 | */ |
663 | Validity peerCertificateValidity() const; |
664 | |
665 | /** |
666 | The CertificateChain for the local host |
667 | certificate. |
668 | */ |
669 | CertificateChain localCertificateChain() const; |
670 | |
671 | /** |
672 | The PrivateKey for the local host |
673 | certificate. |
674 | */ |
675 | PrivateKey localPrivateKey() const; |
676 | |
677 | /** |
678 | The CertificateChain from the peer (other end of |
679 | the connection to the trusted root certificate). |
680 | */ |
681 | CertificateChain peerCertificateChain() const; |
682 | |
683 | // reimplemented |
684 | bool isClosable() const override; |
685 | int bytesAvailable() const override; |
686 | int bytesOutgoingAvailable() const override; |
687 | void close() override; |
688 | void write(const QByteArray &a) override; |
689 | QByteArray read() override; |
690 | void writeIncoming(const QByteArray &a) override; |
691 | QByteArray readOutgoing(int *plainBytes = nullptr) override; |
692 | QByteArray readUnprocessed() override; |
693 | int convertBytesWritten(qint64 encryptedBytes) override; |
694 | |
695 | /** |
696 | Determine the number of packets available to be |
697 | read on the application side. |
698 | |
699 | \note this is only used with DTLS. |
700 | */ |
701 | int packetsAvailable() const; |
702 | |
703 | /** |
704 | Determine the number of packets available to be |
705 | read on the network side. |
706 | |
707 | \note this is only used with DTLS. |
708 | */ |
709 | int packetsOutgoingAvailable() const; |
710 | |
711 | /** |
712 | Return the currently configured maximum packet size |
713 | |
714 | \note this is only used with DTLS |
715 | */ |
716 | int packetMTU() const; |
717 | |
718 | /** |
719 | Set the maximum packet size to use. |
720 | |
721 | \param size the number of bytes to set as the MTU. |
722 | |
723 | \note this is only used with DTLS. |
724 | */ |
725 | void setPacketMTU(int size) const; |
726 | |
727 | Q_SIGNALS: |
728 | /** |
729 | Emitted if a host name is set by the client. At |
730 | this time, the server can inspect the hostName(). |
731 | |
732 | You must call continueAfterStep() in order for %TLS |
733 | processing to resume after this signal is emitted. |
734 | |
735 | This signal is only emitted in server mode. |
736 | |
737 | \sa continueAfterStep |
738 | */ |
739 | void hostNameReceived(); |
740 | |
741 | /** |
742 | Emitted when the server requests a certificate. At |
743 | this time, the client can inspect the issuerList(). |
744 | |
745 | You must call continueAfterStep() in order for %TLS |
746 | processing to resume after this signal is emitted. |
747 | |
748 | This signal is only emitted in client mode. |
749 | |
750 | \sa continueAfterStep |
751 | */ |
752 | void certificateRequested(); |
753 | |
754 | /** |
755 | Emitted when a certificate is received from the peer. |
756 | At this time, you may inspect peerIdentityResult(), |
757 | peerCertificateValidity(), and peerCertificateChain(). |
758 | |
759 | You must call continueAfterStep() in order for %TLS |
760 | processing to resume after this signal is emitted. |
761 | |
762 | \sa continueAfterStep |
763 | */ |
764 | void peerCertificateAvailable(); |
765 | |
766 | /** |
767 | Emitted when the protocol handshake is complete. At |
768 | this time, all available information about the %TLS |
769 | session can be inspected. |
770 | |
771 | You must call continueAfterStep() in order for %TLS |
772 | processing to resume after this signal is emitted. |
773 | |
774 | \sa continueAfterStep |
775 | \sa isHandshaken |
776 | */ |
777 | void handshaken(); |
778 | |
779 | protected: |
780 | /** |
781 | Called when a connection is made to a particular signal |
782 | |
783 | \param signal the name of the signal that has been |
784 | connected to. |
785 | */ |
786 | void connectNotify(const QMetaMethod &signal) override; |
787 | |
788 | /** |
789 | Called when a connection is removed from a particular signal |
790 | |
791 | \param signal the name of the signal that has been |
792 | disconnected from. |
793 | */ |
794 | void disconnectNotify(const QMetaMethod &signal) override; |
795 | |
796 | private: |
797 | Q_DISABLE_COPY(TLS) |
798 | |
799 | class Private; |
800 | friend class Private; |
801 | Private *d; |
802 | }; |
803 | |
804 | /** |
805 | \class SASL qca_securelayer.h QtCrypto |
806 | |
807 | Simple Authentication and Security Layer protocol implementation |
808 | |
809 | This class implements the Simple Authenication and Security Layer protocol, |
810 | which is described in RFC2222 - see |
811 | <a href="http://www.ietf.org/rfc/rfc2222.txt">http://www.ietf.org/rfc/rfc2222.txt</a>. |
812 | |
813 | As the name suggests, %SASL provides authentication (eg, a "login" of some |
814 | form), for a connection oriented protocol, and can also provide protection |
815 | for the subsequent connection. |
816 | |
817 | The %SASL protocol is designed to be extensible, through a range of |
818 | "mechanisms", where a mechanism is the actual authentication method. |
819 | Example mechanisms include Anonymous, LOGIN, Kerberos V4, and GSSAPI. |
820 | Mechanisms can be added (potentially without restarting the server |
821 | application) by the system administrator. |
822 | |
823 | It is important to understand that %SASL is neither "network aware" nor |
824 | "protocol aware". That means that %SASL does not understand how the client |
825 | connects to the server, and %SASL does not understand the actual |
826 | application protocol. |
827 | |
828 | \ingroup UserAPI |
829 | |
830 | */ |
831 | class QCA_EXPORT SASL : public SecureLayer, public Algorithm |
832 | { |
833 | Q_OBJECT |
834 | public: |
835 | /** |
836 | Possible errors that may occur when using %SASL |
837 | */ |
838 | enum Error |
839 | { |
840 | ErrorInit, ///< problem starting up %SASL |
841 | ErrorHandshake, ///< problem during the authentication process |
842 | ErrorCrypt ///< problem at anytime after |
843 | }; |
844 | |
845 | /** |
846 | Possible authentication error states |
847 | */ |
848 | enum AuthCondition |
849 | { |
850 | AuthFail, ///< Generic authentication failure |
851 | NoMechanism, ///< No compatible/appropriate authentication mechanism |
852 | BadProtocol, ///< Bad protocol or cancelled |
853 | BadServer, ///< Server failed mutual authentication (client side only) |
854 | BadAuth, ///< Authentication failure (server side only) |
855 | NoAuthzid, ///< Authorization failure (server side only) |
856 | TooWeak, ///< Mechanism too weak for this user (server side only) |
857 | NeedEncrypt, ///< Encryption is needed in order to use mechanism (server side only) |
858 | Expired, ///< Passphrase expired, has to be reset (server side only) |
859 | Disabled, ///< Account is disabled (server side only) |
860 | NoUser, ///< User not found (server side only) |
861 | RemoteUnavailable ///< Remote service needed for auth is gone (server side only) |
862 | }; |
863 | |
864 | /** |
865 | Authentication requirement flag values |
866 | */ |
867 | enum AuthFlags |
868 | { |
869 | AuthFlagsNone = 0x00, |
870 | AllowPlain = 0x01, |
871 | AllowAnonymous = 0x02, |
872 | RequireForwardSecrecy = 0x04, |
873 | RequirePassCredentials = 0x08, |
874 | RequireMutualAuth = 0x10, |
875 | RequireAuthzidSupport = 0x20 // server-only |
876 | }; |
877 | |
878 | /** |
879 | Mode options for client side sending |
880 | */ |
881 | enum ClientSendMode |
882 | { |
883 | AllowClientSendFirst, |
884 | DisableClientSendFirst |
885 | }; |
886 | |
887 | /** |
888 | Mode options for server side sending |
889 | */ |
890 | enum ServerSendMode |
891 | { |
892 | AllowServerSendLast, |
893 | DisableServerSendLast |
894 | }; |
895 | |
896 | /** |
897 | \class Params qca_securelayer.h QtCrypto |
898 | |
899 | Parameter flags for the %SASL authentication |
900 | |
901 | This is used to indicate which parameters are needed by %SASL |
902 | in order to complete the authentication process. |
903 | |
904 | \ingroup UserAPI |
905 | */ |
906 | class QCA_EXPORT Params |
907 | { |
908 | public: |
909 | Params(); |
910 | |
911 | /** |
912 | Standard constructor. |
913 | |
914 | The concept behind this is that you set each of the |
915 | flags depending on which parameters are needed. |
916 | |
917 | \param user the username is required |
918 | \param authzid the authorization identity is required |
919 | \param pass the password is required |
920 | \param realm the realm is required |
921 | */ |
922 | Params(bool user, bool authzid, bool pass, bool realm); |
923 | |
924 | /** |
925 | Standard copy constructor |
926 | |
927 | \param from the Params object to copy |
928 | */ |
929 | Params(const Params &from); |
930 | ~Params(); |
931 | |
932 | /** |
933 | Standard assignment operator |
934 | |
935 | \param from the Params object to assign from |
936 | */ |
937 | Params &operator=(const Params &from); |
938 | |
939 | /** |
940 | User is needed |
941 | */ |
942 | bool needUsername() const; |
943 | |
944 | /** |
945 | An Authorization ID can be sent if desired |
946 | */ |
947 | bool canSendAuthzid() const; |
948 | |
949 | /** |
950 | Password is needed |
951 | */ |
952 | bool needPassword() const; |
953 | |
954 | /** |
955 | A Realm can be sent if desired |
956 | */ |
957 | bool canSendRealm() const; |
958 | |
959 | private: |
960 | class Private; |
961 | Private *d; |
962 | }; |
963 | |
964 | /** |
965 | Standard constructor |
966 | |
967 | \param parent the parent object for this %SASL connection |
968 | \param provider if specified, the provider to use. If not |
969 | specified, or specified as empty, then any provider is |
970 | acceptable. |
971 | */ |
972 | explicit SASL(QObject *parent = nullptr, const QString &provider = QString()); |
973 | |
974 | ~SASL() override; |
975 | |
976 | /** |
977 | Reset the %SASL mechanism |
978 | */ |
979 | void reset(); |
980 | |
981 | /** |
982 | Specify connection constraints |
983 | |
984 | %SASL supports a range of authentication requirements, and |
985 | a range of security levels. This method allows you to |
986 | specify the requirements for your connection. |
987 | |
988 | \param f the authentication requirements, which you typically |
989 | build using a binary OR function (eg AllowPlain | AllowAnonymous) |
990 | \param s the security level of the encryption, if used. See |
991 | SecurityLevel for details of what each level provides. |
992 | */ |
993 | void setConstraints(AuthFlags f, SecurityLevel s = SL_None); |
994 | |
995 | /** |
996 | \overload |
997 | |
998 | Unless you have a specific reason for directly specifying a |
999 | strength factor, you probably should use the method above. |
1000 | |
1001 | \param f the authentication requirements, which you typically |
1002 | build using a binary OR function (eg AllowPlain | AllowAnonymous) |
1003 | \param minSSF the minimum security strength factor that is required |
1004 | \param maxSSF the maximum security strength factor that is required |
1005 | |
1006 | \note Security strength factors are a rough approximation to key |
1007 | length in the encryption function (eg if you are securing with |
1008 | plain DES, the security strength factor would be 56). |
1009 | */ |
1010 | void setConstraints(AuthFlags f, int minSSF, int maxSSF); |
1011 | |
1012 | /** |
1013 | Specify the local address. |
1014 | |
1015 | \param addr the address of the local part of the connection |
1016 | \param port the port number of the local part of the connection |
1017 | */ |
1018 | void setLocalAddress(const QString &addr, quint16 port); |
1019 | |
1020 | /** |
1021 | Specify the peer address. |
1022 | |
1023 | \param addr the address of the peer side of the connection |
1024 | \param port the port number of the peer side of the connection |
1025 | */ |
1026 | void setRemoteAddress(const QString &addr, quint16 port); |
1027 | |
1028 | /** |
1029 | Specify the id of the externally secured connection |
1030 | |
1031 | \param authid the id of the connection |
1032 | */ |
1033 | void setExternalAuthId(const QString &authid); |
1034 | |
1035 | /** |
1036 | Specify a security strength factor for an externally secured |
1037 | connection |
1038 | |
1039 | \param strength the security strength factor of the connection |
1040 | */ |
1041 | void setExternalSSF(int strength); |
1042 | |
1043 | /** |
1044 | Initialise the client side of the connection |
1045 | |
1046 | startClient must be called on the client side of the connection. |
1047 | clientStarted will be emitted when the operation is completed. |
1048 | |
1049 | \param service the name of the service |
1050 | \param host the client side host name |
1051 | \param mechlist the list of mechanisms which can be used |
1052 | \param mode the mode to use on the client side |
1053 | */ |
1054 | void startClient(const QString &service, |
1055 | const QString &host, |
1056 | const QStringList &mechlist, |
1057 | ClientSendMode mode = AllowClientSendFirst); |
1058 | |
1059 | /** |
1060 | Initialise the server side of the connection |
1061 | |
1062 | startServer must be called on the server side of the connection. |
1063 | serverStarted will be emitted when the operation is completed. |
1064 | |
1065 | \param service the name of the service |
1066 | \param host the server side host name |
1067 | \param realm the realm to use |
1068 | \param mode which mode to use on the server side |
1069 | */ |
1070 | void startServer(const QString &service, |
1071 | const QString &host, |
1072 | const QString &realm, |
1073 | ServerSendMode mode = DisableServerSendLast); |
1074 | |
1075 | /** |
1076 | Process the first step in server mode (server) |
1077 | |
1078 | Call this with the mechanism selected by the client. If there |
1079 | is initial client data, call the other version of this function |
1080 | instead. |
1081 | |
1082 | \param mech the mechanism to be used. |
1083 | */ |
1084 | void putServerFirstStep(const QString &mech); |
1085 | |
1086 | /** |
1087 | Process the first step in server mode (server) |
1088 | |
1089 | Call this with the mechanism selected by the client, and initial |
1090 | client data. If there is no initial client data, call the other |
1091 | version of this function instead. |
1092 | |
1093 | \param mech the mechanism to be used |
1094 | \param clientInit the initial data provided by the client side |
1095 | */ |
1096 | void putServerFirstStep(const QString &mech, const QByteArray &clientInit); |
1097 | |
1098 | /** |
1099 | Process an authentication step |
1100 | |
1101 | Call this with authentication data received from the network. |
1102 | The only exception is the first step in server mode, in which |
1103 | case putServerFirstStep must be called. |
1104 | |
1105 | \param stepData the authentication data from the network |
1106 | */ |
1107 | void putStep(const QByteArray &stepData); |
1108 | |
1109 | /** |
1110 | Return the mechanism selected (client) |
1111 | */ |
1112 | QString mechanism() const; |
1113 | |
1114 | /** |
1115 | Return the mechanism list (server) |
1116 | */ |
1117 | QStringList mechanismList() const; |
1118 | |
1119 | /** |
1120 | Return the realm list, if available (client) |
1121 | */ |
1122 | QStringList realmList() const; |
1123 | |
1124 | /** |
1125 | Return the security strength factor of the connection |
1126 | */ |
1127 | int ssf() const; |
1128 | |
1129 | /** |
1130 | Return the error code |
1131 | */ |
1132 | Error errorCode() const; |
1133 | |
1134 | /** |
1135 | Return the reason for authentication failure |
1136 | */ |
1137 | AuthCondition authCondition() const; |
1138 | |
1139 | /** |
1140 | Specify the username to use in authentication |
1141 | |
1142 | \param user the username to use |
1143 | */ |
1144 | void setUsername(const QString &user); |
1145 | |
1146 | /** |
1147 | Specify the authorization identity to use in authentication |
1148 | |
1149 | \param auth the authorization identity to use |
1150 | */ |
1151 | void setAuthzid(const QString &auth); |
1152 | |
1153 | /** |
1154 | Specify the password to use in authentication |
1155 | |
1156 | \param pass the password to use |
1157 | */ |
1158 | void setPassword(const SecureArray &pass); |
1159 | |
1160 | /** |
1161 | Specify the realm to use in authentication |
1162 | |
1163 | \param realm the realm to use |
1164 | */ |
1165 | void setRealm(const QString &realm); |
1166 | |
1167 | /** |
1168 | Continue negotiation after parameters have been set (client) |
1169 | */ |
1170 | void continueAfterParams(); |
1171 | |
1172 | /** |
1173 | Continue negotiation after auth ids have been checked (server) |
1174 | */ |
1175 | void continueAfterAuthCheck(); |
1176 | |
1177 | // reimplemented |
1178 | int bytesAvailable() const override; |
1179 | int bytesOutgoingAvailable() const override; |
1180 | void write(const QByteArray &a) override; |
1181 | QByteArray read() override; |
1182 | void writeIncoming(const QByteArray &a) override; |
1183 | QByteArray readOutgoing(int *plainBytes = nullptr) override; |
1184 | int convertBytesWritten(qint64 encryptedBytes) override; |
1185 | |
1186 | Q_SIGNALS: |
1187 | /** |
1188 | This signal is emitted when the client has been successfully |
1189 | started |
1190 | |
1191 | \param clientInit true if the client should send an initial |
1192 | response to the server |
1193 | \param clientInitData the initial response to send to the server. |
1194 | Do note that there is a difference in SASL between an empty initial |
1195 | response and no initial response, and so even if clientInitData is |
1196 | an empty array, you still need to send an initial response if |
1197 | clientInit is true. |
1198 | */ |
1199 | void clientStarted(bool clientInit, const QByteArray &clientInitData); |
1200 | |
1201 | /** |
1202 | This signal is emitted after the server has been |
1203 | successfully started |
1204 | */ |
1205 | void serverStarted(); |
1206 | |
1207 | /** |
1208 | This signal is emitted when there is data required |
1209 | to be sent over the network to complete the next |
1210 | step in the authentication process. |
1211 | |
1212 | \param stepData the data to send over the network |
1213 | */ |
1214 | void nextStep(const QByteArray &stepData); |
1215 | |
1216 | /** |
1217 | This signal is emitted when the client needs |
1218 | additional parameters |
1219 | |
1220 | After receiving this signal, the application should set |
1221 | the required parameter values appropriately and then call |
1222 | continueAfterParams(). |
1223 | |
1224 | \param params the parameters that are required by the client |
1225 | */ |
1226 | void needParams(const QCA::SASL::Params ¶ms); |
1227 | |
1228 | /** |
1229 | This signal is emitted when the server needs to |
1230 | perform the authentication check |
1231 | |
1232 | If the user and authzid are valid, call continueAfterAuthCheck(). |
1233 | |
1234 | \param user the user identification name |
1235 | \param authzid the user authorization name |
1236 | */ |
1237 | void authCheck(const QString &user, const QString &authzid); |
1238 | |
1239 | /** |
1240 | This signal is emitted when authentication is complete. |
1241 | */ |
1242 | void authenticated(); |
1243 | |
1244 | private: |
1245 | Q_DISABLE_COPY(SASL) |
1246 | |
1247 | class Private; |
1248 | friend class Private; |
1249 | Private *d; |
1250 | }; |
1251 | |
1252 | } |
1253 | |
1254 | #endif |
1255 | |