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
40namespace 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 */
59enum 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*/
104class QCA_EXPORT SecureLayer : public QObject
105{
106 Q_OBJECT
107public:
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
197Q_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
226private:
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*/
238class QCA_EXPORT TLSSession : public Algorithm
239{
240public:
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*/
289class QCA_EXPORT TLS : public SecureLayer, public Algorithm
290{
291 Q_OBJECT
292public:
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
467Certificate someCert = ...
468PrivateKey someKey = ...
469
470// see if the server will take our cert
471CertificateInfoOrdered issuerInfo = someCert.issuerInfoOrdered().dnOnly();
472foreach(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
727Q_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
779protected:
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
796private:
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*/
831class QCA_EXPORT SASL : public SecureLayer, public Algorithm
832{
833 Q_OBJECT
834public:
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
1186Q_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 &params);
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
1244private:
1245 Q_DISABLE_COPY(SASL)
1246
1247 class Private;
1248 friend class Private;
1249 Private *d;
1250};
1251
1252}
1253
1254#endif
1255

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