QCA

qca_securelayer.h
Go to the documentation of this file.
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
431
432 /**
433 The security level required for this link
434
435 \param s the level required for this link.
436 */
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 */
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 */
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 */
531
532 /**
533 Returns the host name specified or an empty string if no host
534 name is specified.
535 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
664
665 /**
666 The CertificateChain for the local host
667 certificate.
668 */
670
671 /**
672 The PrivateKey for the local host
673 certificate.
674 */
676
677 /**
678 The CertificateChain from the peer (other end of
679 the connection to the trusted root certificate).
680 */
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;
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
882 {
883 AllowClientSendFirst,
884 DisableClientSendFirst
885 };
886
887 /**
888 Mode options for server side sending
889 */
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 */
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 */
1113
1114 /**
1115 Return the mechanism list (server)
1116 */
1118
1119 /**
1120 Return the realm list, if available (client)
1121 */
1123
1124 /**
1125 Return the security strength factor of the connection
1126 */
1127 int ssf() const;
1128
1129 /**
1130 Return the error code
1131 */
1133
1134 /**
1135 Return the reason for authentication failure
1136 */
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 */
1171
1172 /**
1173 Continue negotiation after auth ids have been checked (server)
1174 */
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 */
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 */
1243
1244private:
1245 Q_DISABLE_COPY(SASL)
1246
1247 class Private;
1248 friend class Private;
1249 Private *d;
1250};
1251
1252}
1253
1254#endif
General superclass for an algorithm.
Definition qca_core.h:1164
A chain of related Certificates.
Definition qca_cert.h:1226
Bundle of Certificates and CRLs.
Definition qca_cert.h:1929
Certificate chain and private key pair.
Definition qca_cert.h:2176
Generic private key.
Parameter flags for the SASL authentication.
bool needPassword() const
Password is needed.
bool canSendAuthzid() const
An Authorization ID can be sent if desired.
bool needUsername() const
User is needed.
bool canSendRealm() const
A Realm can be sent if desired.
Params(bool user, bool authzid, bool pass, bool realm)
Standard constructor.
Params & operator=(const Params &from)
Standard assignment operator.
Params(const Params &from)
Standard copy constructor.
Simple Authentication and Security Layer protocol implementation.
void startServer(const QString &service, const QString &host, const QString &realm, ServerSendMode mode=DisableServerSendLast)
Initialise the server side of the connection.
void putServerFirstStep(const QString &mech)
Process the first step in server mode (server)
void setUsername(const QString &user)
Specify the username to use in authentication.
void setExternalSSF(int strength)
Specify a security strength factor for an externally secured connection.
Error errorCode() const
Return the error code.
void authCheck(const QString &user, const QString &authzid)
This signal is emitted when the server needs to perform the authentication check.
void continueAfterParams()
Continue negotiation after parameters have been set (client)
void write(const QByteArray &a) override
This method writes unencrypted (plain) data to the SecureLayer implementation.
void startClient(const QString &service, const QString &host, const QStringList &mechlist, ClientSendMode mode=AllowClientSendFirst)
Initialise the client side of the connection.
int convertBytesWritten(qint64 encryptedBytes) override
Convert encrypted bytes written to plain text bytes written.
SASL(QObject *parent=nullptr, const QString &provider=QString())
Standard constructor.
void setConstraints(AuthFlags f, SecurityLevel s=SL_None)
Specify connection constraints.
void setAuthzid(const QString &auth)
Specify the authorization identity to use in authentication.
void nextStep(const QByteArray &stepData)
This signal is emitted when there is data required to be sent over the network to complete the next s...
void continueAfterAuthCheck()
Continue negotiation after auth ids have been checked (server)
void writeIncoming(const QByteArray &a) override
This method accepts encoded (typically encrypted) data for processing.
AuthCondition
Possible authentication error states.
@ NeedEncrypt
Encryption is needed in order to use mechanism (server side only)
@ TooWeak
Mechanism too weak for this user (server side only)
@ AuthFail
Generic authentication failure.
@ BadProtocol
Bad protocol or cancelled.
@ NoUser
User not found (server side only)
@ NoMechanism
No compatible/appropriate authentication mechanism.
@ BadServer
Server failed mutual authentication (client side only)
@ Expired
Passphrase expired, has to be reset (server side only)
@ Disabled
Account is disabled (server side only)
@ BadAuth
Authentication failure (server side only)
@ NoAuthzid
Authorization failure (server side only)
ServerSendMode
Mode options for server side sending.
QString mechanism() const
Return the mechanism selected (client)
void serverStarted()
This signal is emitted after the server has been successfully started.
void setPassword(const SecureArray &pass)
Specify the password to use in authentication.
void setExternalAuthId(const QString &authid)
Specify the id of the externally secured connection.
QStringList realmList() const
Return the realm list, if available (client)
int bytesOutgoingAvailable() const override
Returns the number of bytes available to be readOutgoing() on the network side.
void clientStarted(bool clientInit, const QByteArray &clientInitData)
This signal is emitted when the client has been successfully started.
QByteArray read() override
This method reads decrypted (plain) data from the SecureLayer implementation.
ClientSendMode
Mode options for client side sending.
void needParams(const QCA::SASL::Params &params)
This signal is emitted when the client needs additional parameters.
QStringList mechanismList() const
Return the mechanism list (server)
Error
Possible errors that may occur when using SASL.
@ ErrorInit
problem starting up SASL
@ ErrorHandshake
problem during the authentication process
int ssf() const
Return the security strength factor of the connection.
void setRemoteAddress(const QString &addr, quint16 port)
Specify the peer address.
void setConstraints(AuthFlags f, int minSSF, int maxSSF)
This is an overloaded member function, provided for convenience. It differs from the above function o...
void putServerFirstStep(const QString &mech, const QByteArray &clientInit)
Process the first step in server mode (server)
void setRealm(const QString &realm)
Specify the realm to use in authentication.
void reset()
Reset the SASL mechanism.
int bytesAvailable() const override
Returns the number of bytes available to be read() on the application side.
AuthCondition authCondition() const
Return the reason for authentication failure.
void authenticated()
This signal is emitted when authentication is complete.
void setLocalAddress(const QString &addr, quint16 port)
Specify the local address.
QByteArray readOutgoing(int *plainBytes=nullptr) override
This method provides encoded (typically encrypted) data.
void putStep(const QByteArray &stepData)
Process an authentication step.
AuthFlags
Authentication requirement flag values.
Secure array of bytes.
Definition qca_tools.h:317
Abstract interface to a security layer.
virtual void write(const QByteArray &a)=0
This method writes unencrypted (plain) data to the SecureLayer implementation.
virtual int convertBytesWritten(qint64 encryptedBytes)=0
Convert encrypted bytes written to plain text bytes written.
virtual QByteArray readUnprocessed()
This allows you to read data without having it decrypted first.
SecureLayer(QObject *parent=nullptr)
Constructor for an abstract secure communications layer.
virtual void writeIncoming(const QByteArray &a)=0
This method accepts encoded (typically encrypted) data for processing.
virtual int bytesAvailable() const =0
Returns the number of bytes available to be read() on the application side.
virtual QByteArray readOutgoing(int *plainBytes=nullptr)=0
This method provides encoded (typically encrypted) data.
void error()
This signal is emitted when an error is detected.
virtual void close()
Close the link.
void readyReadOutgoing()
This signal is emitted when SecureLayer has encrypted (network side) data ready to be read.
virtual QByteArray read()=0
This method reads decrypted (plain) data from the SecureLayer implementation.
void closed()
This signal is emitted when the SecureLayer connection is closed.
virtual bool isClosable() const
Returns true if the layer has a meaningful "close".
virtual int bytesOutgoingAvailable() const =0
Returns the number of bytes available to be readOutgoing() on the network side.
void readyRead()
This signal is emitted when SecureLayer has decrypted (application side) data ready to be read.
Session token, used for TLS resuming.
TLSSession & operator=(const TLSSession &from)
Assignment operator.
TLSSession(const TLSSession &from)
Copy constructor.
bool isNull() const
Test if the session token is valid.
Transport Layer Security / Secure Socket Layer.
void setConstraints(SecurityLevel s)
The security level required for this link.
int packetsOutgoingAvailable() const
Determine the number of packets available to be read on the network side.
void setPacketMTU(int size) const
Set the maximum packet size to use.
TLS(Mode mode, QObject *parent=nullptr, const QString &provider=QString())
Constructor for Transport Layer Security connection.
int cipherMaxBits() const
The number of bits of security that the cipher could use.
void write(const QByteArray &a) override
This method writes unencrypted (plain) data to the SecureLayer implementation.
void startClient(const QString &host=QString())
Start the TLS/SSL connection as a client.
Version version() const
The protocol version that is in use for this connection.
void writeIncoming(const QByteArray &a) override
This method accepts encoded (typically encrypted) data for processing.
Mode
Operating mode.
@ Stream
stream mode
void setConstraints(int minSSF, int maxSSF)
This is an overloaded member function, provided for convenience. It differs from the above function o...
void continueAfterStep()
Resumes TLS processing.
PrivateKey localPrivateKey() const
The PrivateKey for the local host certificate.
void hostNameReceived()
Emitted if a host name is set by the client.
int cipherBits() const
The number of effective bits of security being used for this connection.
int bytesOutgoingAvailable() const override
Returns the number of bytes available to be readOutgoing() on the network side.
~TLS() override
Destructor.
QString hostName() const
Returns the host name specified or an empty string if no host name is specified.
TLSSession session() const
The session object of the TLS connection, which can be used for resuming.
Error
Type of error.
@ ErrorHandshake
problem during the negotiation
@ ErrorCertKeyMismatch
certificate and private key don't match
@ ErrorSignerExpired
local certificate is expired
@ ErrorSignerInvalid
local certificate is invalid in some way
@ ErrorInit
problem starting up TLS
void setTrustedCertificates(const CertificateCollection &trusted)
Set up the set of trusted certificates that will be used to verify that the certificate provided is v...
void reset()
Reset the connection.
bool isClosable() const override
Returns true if the layer has a meaningful "close".
void startServer()
Start the TLS/SSL connection as a server.
void setConstraints(const QStringList &cipherSuiteList)
This is an overloaded member function, provided for convenience. It differs from the above function o...
QStringList supportedCipherSuites(const Version &version=TLS_v1) const
Get the list of cipher suites that are available for use.
QList< CertificateInfoOrdered > issuerList() const
CertificateCollection trustedCertificates() const
Return the trusted certificates set for this object.
IdentityResult peerIdentityResult() const
After the SSL/TLS handshake is complete, this method allows you to determine if the other end of the ...
QByteArray readOutgoing(int *plainBytes=nullptr) override
This method provides encoded (typically encrypted) data.
IdentityResult
Type of identity.
@ HostMismatch
valid cert provided, but wrong owner
@ InvalidCertificate
invalid cert
@ Valid
identity is verified
TLS(QObject *parent=nullptr, const QString &provider=QString())
Constructor for Transport Layer Security connection.
bool canSetHostName() const
Test if the link can specify a hostname (Server Name Indication)
void close() override
Close the link.
QByteArray read() override
This method reads decrypted (plain) data from the SecureLayer implementation.
void connectNotify(const QMetaMethod &signal) override
Called when a connection is made to a particular signal.
bool isHandshaken() const
test if the handshake is complete
int packetsAvailable() const
Determine the number of packets available to be read on the application side.
Validity peerCertificateValidity() const
After the SSL/TLS handshake is valid, this method allows you to check if the received certificate fro...
QByteArray readUnprocessed() override
This allows you to read data without having it decrypted first.
Version
Version of TLS or SSL.
@ SSL_v2
Secure Socket Layer, version 2.
@ TLS_v1
Transport Layer Security, version 1.
@ SSL_v3
Secure Socket Layer, version 3.
int packetMTU() const
Return the currently configured maximum packet size.
Error errorCode() const
This method returns the type of error that has occurred.
bool compressionEnabled() const
Returns true if compression is enabled.
bool canCompress() const
Test if the link can use compression.
int convertBytesWritten(qint64 encryptedBytes) override
Convert encrypted bytes written to plain text bytes written.
CertificateChain peerCertificateChain() const
The CertificateChain from the peer (other end of the connection to the trusted root certificate).
int bytesAvailable() const override
Returns the number of bytes available to be read() on the application side.
void peerCertificateAvailable()
Emitted when a certificate is received from the peer.
QString cipherSuite() const
The cipher suite that has been negotiated for this connection.
void setCertificate(const CertificateChain &cert, const PrivateKey &key)
The local certificate to use.
bool isCompressed() const
test if the link is compressed
void handshaken()
Emitted when the protocol handshake is complete.
void disconnectNotify(const QMetaMethod &signal) override
Called when a connection is removed from a particular signal.
void setIssuerList(const QList< CertificateInfoOrdered > &issuers)
Sets the issuer list to present to the client.
void setSession(const TLSSession &session)
Resume a TLS session using the given session object.
void certificateRequested()
Emitted when the server requests a certificate.
void setCertificate(const KeyBundle &kb)
This is an overloaded member function, provided for convenience. It differs from the above function o...
CertificateChain localCertificateChain() const
The CertificateChain for the local host certificate.
void setCompressionEnabled(bool b)
Set the link to use compression.
QCA - the Qt Cryptographic Architecture.
Definition qca_basic.h:41
Validity
The validity (or otherwise) of a certificate.
Definition qca_cert.h:497
SecurityLevel
Specify the lower-bound for acceptable TLS/SASL security layers.
@ SL_Baseline
must be 128 bit or more
@ SL_Integrity
must at least get integrity protection
@ SL_High
must be more than 128 bit
@ SL_Export
must be export level bits or more
@ SL_Highest
SL_High or max possible, whichever is greater.
@ SL_None
indicates that no security is ok
Header file for PGP key and X.509 certificate related classes.
Header file for core QCA infrastructure.
Header file for PublicKey and PrivateKey related classes.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:47:19 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.