Qt Cryptographic Architecture
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 
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 
60 {
66  SL_Highest
67 };
68 
104 class QCA_EXPORT SecureLayer : public QObject
105 {
106  Q_OBJECT
107 public:
114  SecureLayer(QObject *parent = nullptr);
115 
119  virtual bool isClosable() const;
120 
125  virtual int bytesAvailable() const = 0;
126 
131  virtual int bytesOutgoingAvailable() const = 0;
132 
140  virtual void close();
141 
149  virtual void write(const QByteArray &a) = 0;
150 
157  virtual QByteArray read() = 0;
158 
168  virtual void writeIncoming(const QByteArray &a) = 0;
169 
179  virtual QByteArray readOutgoing(int *plainBytes = nullptr) = 0;
180 
188  virtual QByteArray readUnprocessed();
189 
195  virtual int convertBytesWritten(qint64 encryptedBytes) = 0;
196 
197 Q_SIGNALS:
204  void readyRead();
205 
213 
218  void closed();
219 
224  void error();
225 
226 private:
227  Q_DISABLE_COPY(SecureLayer)
228 };
229 
238 class QCA_EXPORT TLSSession : public Algorithm
239 {
240 public:
241  TLSSession();
242 
248  TLSSession(const TLSSession &from);
249 
250  ~TLSSession() override;
251 
258 
262  bool isNull() const;
263 };
264 
289 class QCA_EXPORT TLS : public SecureLayer, public Algorithm
290 {
291  Q_OBJECT
292 public:
296  enum Mode
297  {
299  Datagram
300  };
301 
305  enum Version
306  {
310  DTLS_v1
311  };
312 
316  enum Error
317  {
323  ErrorCrypt
324  };
325 
330  {
334  NoCertificate
335  };
336 
348  explicit TLS(QObject *parent = nullptr, const QString &provider = QString());
349 
361  explicit TLS(Mode mode, QObject *parent = nullptr, const QString &provider = QString());
362 
366  ~TLS() override;
367 
371  void reset();
372 
387  QStringList supportedCipherSuites(const Version &version = TLS_v1) const;
388 
402  void setCertificate(const CertificateChain &cert, const PrivateKey &key);
403 
412  void setCertificate(const KeyBundle &kb);
413 
418 
431 
438 
447  void setConstraints(int minSSF, int maxSSF);
448 
459  void setConstraints(const QStringList &cipherSuiteList);
460 
484 
492 
498  void setSession(const TLSSession &session);
499 
505  bool canCompress() const;
506 
513  bool canSetHostName() const;
514 
522  bool compressionEnabled() const;
523 
530  void setCompressionEnabled(bool b);
531 
536  QString hostName() const;
537 
557  void startClient(const QString &host = QString());
558 
562  void startServer();
563 
574 
582  bool isHandshaken() const;
583 
589  bool isCompressed() const;
590 
594  Version version() const;
595 
602  QString cipherSuite() const;
603 
613  int cipherBits() const;
614 
621  int cipherMaxBits() const;
622 
628 
634  Error errorCode() const;
635 
654 
664 
670 
676 
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 
701  int packetsAvailable() const;
702 
710 
716  int packetMTU() const;
717 
725  void setPacketMTU(int size) const;
726 
727 Q_SIGNALS:
740 
753 
765 
777  void handshaken();
778 
779 protected:
786  void connectNotify(const QMetaMethod &signal) override;
787 
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 
831 class QCA_EXPORT SASL : public SecureLayer, public Algorithm
832 {
833  Q_OBJECT
834 public:
838  enum Error
839  {
842  ErrorCrypt
843  };
844 
849  {
861  RemoteUnavailable
862  };
863 
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 
882  {
883  AllowClientSendFirst,
884  DisableClientSendFirst
885  };
886 
891  {
892  AllowServerSendLast,
893  DisableServerSendLast
894  };
895 
906  class QCA_EXPORT Params
907  {
908  public:
909  Params();
910 
922  Params(bool user, bool authzid, bool pass, bool realm);
923 
929  Params(const Params &from);
930  ~Params();
931 
937  Params &operator=(const Params &from);
938 
942  bool needUsername() const;
943 
947  bool canSendAuthzid() const;
948 
952  bool needPassword() const;
953 
957  bool canSendRealm() const;
958 
959  private:
960  class Private;
961  Private *d;
962  };
963 
972  explicit SASL(QObject *parent = nullptr, const QString &provider = QString());
973 
974  ~SASL() override;
975 
979  void reset();
980 
994 
1010  void setConstraints(AuthFlags f, int minSSF, int maxSSF);
1011 
1018  void setLocalAddress(const QString &addr, quint16 port);
1019 
1026  void setRemoteAddress(const QString &addr, quint16 port);
1027 
1033  void setExternalAuthId(const QString &authid);
1034 
1041  void setExternalSSF(int strength);
1042 
1054  void startClient(const QString &service,
1055  const QString &host,
1056  const QStringList &mechlist,
1057  ClientSendMode mode = AllowClientSendFirst);
1058 
1070  void startServer(const QString &service,
1071  const QString &host,
1072  const QString &realm,
1073  ServerSendMode mode = DisableServerSendLast);
1074 
1084  void putServerFirstStep(const QString &mech);
1085 
1096  void putServerFirstStep(const QString &mech, const QByteArray &clientInit);
1097 
1107  void putStep(const QByteArray &stepData);
1108 
1112  QString mechanism() const;
1113 
1117  QStringList mechanismList() const;
1118 
1122  QStringList realmList() const;
1123 
1127  int ssf() const;
1128 
1132  Error errorCode() const;
1133 
1138 
1144  void setUsername(const QString &user);
1145 
1151  void setAuthzid(const QString &auth);
1152 
1158  void setPassword(const SecureArray &pass);
1159 
1165  void setRealm(const QString &realm);
1166 
1171 
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:
1199  void clientStarted(bool clientInit, const QByteArray &clientInitData);
1200 
1206 
1214  void nextStep(const QByteArray &stepData);
1215 
1226  void needParams(const QCA::SASL::Params &params);
1227 
1237  void authCheck(const QString &user, const QString &authzid);
1238 
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
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.
Definition: qca_publickey.h:833
Parameter flags for the SASL authentication.
Definition: qca_securelayer.h:907
bool needPassword() const
Password is needed.
bool canSendAuthzid() const
An Authorization ID can be sent if desired.
Params & operator=(const Params &from)
Standard assignment operator.
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(const Params &from)
Standard copy constructor.
Simple Authentication and Security Layer protocol implementation.
Definition: qca_securelayer.h:832
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.
Definition: qca_securelayer.h:849
@ NeedEncrypt
Encryption is needed in order to use mechanism (server side only)
Definition: qca_securelayer.h:857
@ TooWeak
Mechanism too weak for this user (server side only)
Definition: qca_securelayer.h:856
@ AuthFail
Generic authentication failure.
Definition: qca_securelayer.h:850
@ BadProtocol
Bad protocol or cancelled.
Definition: qca_securelayer.h:852
@ NoUser
User not found (server side only)
Definition: qca_securelayer.h:860
@ NoMechanism
No compatible/appropriate authentication mechanism.
Definition: qca_securelayer.h:851
@ BadServer
Server failed mutual authentication (client side only)
Definition: qca_securelayer.h:853
@ Expired
Passphrase expired, has to be reset (server side only)
Definition: qca_securelayer.h:858
@ Disabled
Account is disabled (server side only)
Definition: qca_securelayer.h:859
@ BadAuth
Authentication failure (server side only)
Definition: qca_securelayer.h:854
@ NoAuthzid
Authorization failure (server side only)
Definition: qca_securelayer.h:855
ServerSendMode
Mode options for server side sending.
Definition: qca_securelayer.h:891
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.
Definition: qca_securelayer.h:882
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.
Definition: qca_securelayer.h:839
@ ErrorInit
problem starting up SASL
Definition: qca_securelayer.h:840
@ ErrorHandshake
problem during the authentication process
Definition: qca_securelayer.h:841
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.
Definition: qca_securelayer.h:868
Secure array of bytes.
Definition: qca_tools.h:317
Abstract interface to a security layer.
Definition: qca_securelayer.h:105
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.
Definition: qca_securelayer.h:239
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.
Definition: qca_securelayer.h:290
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.
Definition: qca_securelayer.h:297
@ Stream
stream mode
Definition: qca_securelayer.h:298
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.
QList< CertificateInfoOrdered > issuerList() const
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.
Definition: qca_securelayer.h:317
@ ErrorHandshake
problem during the negotiation
Definition: qca_securelayer.h:322
@ ErrorCertKeyMismatch
certificate and private key don't match
Definition: qca_securelayer.h:320
@ ErrorSignerExpired
local certificate is expired
Definition: qca_securelayer.h:318
@ ErrorSignerInvalid
local certificate is invalid in some way
Definition: qca_securelayer.h:319
@ ErrorInit
problem starting up TLS
Definition: qca_securelayer.h:321
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.
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.
Definition: qca_securelayer.h:330
@ HostMismatch
valid cert provided, but wrong owner
Definition: qca_securelayer.h:332
@ InvalidCertificate
invalid cert
Definition: qca_securelayer.h:333
@ Valid
identity is verified
Definition: qca_securelayer.h:331
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.
Definition: qca_securelayer.h:306
@ SSL_v2
Secure Socket Layer, version 2.
Definition: qca_securelayer.h:309
@ TLS_v1
Transport Layer Security, version 1.
Definition: qca_securelayer.h:307
@ SSL_v3
Secure Socket Layer, version 3.
Definition: qca_securelayer.h:308
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.
Definition: qca_securelayer.h:60
@ SL_Baseline
must be 128 bit or more
Definition: qca_securelayer.h:64
@ SL_Integrity
must at least get integrity protection
Definition: qca_securelayer.h:62
@ SL_High
must be more than 128 bit
Definition: qca_securelayer.h:65
@ SL_Export
must be export level bits or more
Definition: qca_securelayer.h:63
@ SL_Highest
SL_High or max possible, whichever is greater.
Definition: qca_securelayer.h:66
@ SL_None
indicates that no security is ok
Definition: qca_securelayer.h:61
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.