QCA::TLS

#include <QtCrypto>

Inheritance diagram for QCA::TLS:

Public Types

enum  Error {
  ErrorSignerExpired, ErrorSignerInvalid, ErrorCertKeyMismatch, ErrorInit,
  ErrorHandshake, ErrorCrypt
}
 
enum  IdentityResult { Valid, HostMismatch, InvalidCertificate, NoCertificate }
 
enum  Mode { Stream, Datagram }
 
enum  Version { TLS_v1, SSL_v3, SSL_v2, DTLS_v1 }
 

Signals

void certificateRequested ()
 
void handshaken ()
 
void hostNameReceived ()
 
void peerCertificateAvailable ()
 
- Signals inherited from QCA::SecureLayer
void closed ()
 
void error ()
 
void readyRead ()
 
void readyReadOutgoing ()
 

Public Member Functions

 TLS (QObject *parent=nullptr, const QString &provider=QString())
 
 TLS (Mode mode, QObject *parent=nullptr, const QString &provider=QString())
 
 ~TLS () override
 
int bytesAvailable () const override
 
int bytesOutgoingAvailable () const override
 
bool canCompress () const
 
bool canSetHostName () const
 
int cipherBits () const
 
int cipherMaxBits () const
 
QString cipherSuite () const
 
void close () override
 
bool compressionEnabled () const
 
void continueAfterStep ()
 
int convertBytesWritten (qint64 encryptedBytes) override
 
Error errorCode () const
 
QString hostName () const
 
bool isClosable () const override
 
bool isCompressed () const
 
bool isHandshaken () const
 
QList< CertificateInfoOrderedissuerList () const
 
CertificateChain localCertificateChain () const
 
PrivateKey localPrivateKey () const
 
int packetMTU () const
 
int packetsAvailable () const
 
int packetsOutgoingAvailable () const
 
CertificateChain peerCertificateChain () const
 
Validity peerCertificateValidity () const
 
IdentityResult peerIdentityResult () const
 
QByteArray read () override
 
QByteArray readOutgoing (int *plainBytes=nullptr) override
 
QByteArray readUnprocessed () override
 
void reset ()
 
TLSSession session () const
 
void setCertificate (const CertificateChain &cert, const PrivateKey &key)
 
void setCertificate (const KeyBundle &kb)
 
void setCompressionEnabled (bool b)
 
void setConstraints (SecurityLevel s)
 
void setConstraints (int minSSF, int maxSSF)
 
void setConstraints (const QStringList &cipherSuiteList)
 
void setIssuerList (const QList< CertificateInfoOrdered > &issuers)
 
void setPacketMTU (int size) const
 
void setSession (const TLSSession &session)
 
void setTrustedCertificates (const CertificateCollection &trusted)
 
void startClient (const QString &host=QString())
 
void startServer ()
 
QStringList supportedCipherSuites (const Version &version=TLS_v1) const
 
CertificateCollection trustedCertificates () const
 
Version version () const
 
void write (const QByteArray &a) override
 
void writeIncoming (const QByteArray &a) override
 
- Public Member Functions inherited from QCA::SecureLayer
 SecureLayer (QObject *parent=nullptr)
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 
- Public Member Functions inherited from QCA::Algorithm
 Algorithm (const Algorithm &from)
 
void change (Provider::Context *c)
 
void change (const QString &type, const QString &provider)
 
Provider::Contextcontext ()
 
const Provider::Contextcontext () const
 
Algorithmoperator= (const Algorithm &from)
 
Providerprovider () const
 
Provider::ContexttakeContext ()
 
QString type () const
 

Protected Member Functions

void connectNotify (const QMetaMethod &signal) override
 
void disconnectNotify (const QMetaMethod &signal) override
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void customEvent (QEvent *event)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 
- Protected Member Functions inherited from QCA::Algorithm
 Algorithm ()
 
 Algorithm (const QString &type, const QString &provider)
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 

Detailed Description

Transport Layer Security / Secure Socket Layer.

Transport Layer Security (TLS) is the current state-of-the-art in secure transport mechanisms over the internet. It can be used in a way where only one side of the link needs to authenticate to the other. This makes it very useful for servers to provide their identity to clients. Note that is is possible to use TLS to authenticate both client and server.

TLS is a IETF standard (RFC2712 for TLS version 1.0, and RFC4346 for TLS version 1.1) based on earlier Netscape work on Secure Socket Layer (SSL version 2 and SSL version 3). New applications should use at least TLS 1.0, and SSL version 2 should be avoided due to known security problems.

Examples:
sslservtest.cpp, ssltest.cpp, and tlssocket.cpp.

Definition at line 289 of file qca_securelayer.h.

Member Enumeration Documentation

Type of error.

Enumerator
ErrorSignerExpired 

local certificate is expired

ErrorSignerInvalid 

local certificate is invalid in some way

ErrorCertKeyMismatch 

certificate and private key don't match

ErrorInit 

problem starting up TLS

ErrorHandshake 

problem during the negotiation

ErrorCrypt 

problem at anytime after

Definition at line 316 of file qca_securelayer.h.

Type of identity.

Enumerator
Valid 

identity is verified

HostMismatch 

valid cert provided, but wrong owner

InvalidCertificate 

invalid cert

NoCertificate 

identity unknown

Definition at line 329 of file qca_securelayer.h.

Operating mode.

Enumerator
Stream 

stream mode

Datagram 

datagram mode

Definition at line 296 of file qca_securelayer.h.

Version of TLS or SSL.

Enumerator
TLS_v1 

Transport Layer Security, version 1.

SSL_v3 

Secure Socket Layer, version 3.

SSL_v2 

Secure Socket Layer, version 2.

DTLS_v1 

Datagram Transport Layer Security, version 1.

Definition at line 305 of file qca_securelayer.h.

Constructor & Destructor Documentation

QCA::TLS::TLS ( QObject parent = nullptr,
const QString provider = QString() 
)
explicit

Constructor for Transport Layer Security connection.

This produces a Stream (normal TLS) rather than Datagram (DTLS) object. If you want to do DTLS, see below.

Parameters
parentthe parent object for this object
providerthe name of the provider, if a specific provider is required
QCA::TLS::TLS ( Mode  mode,
QObject parent = nullptr,
const QString provider = QString() 
)
explicit

Constructor for Transport Layer Security connection.

This constructor can be used for both normal TLS (set mode to TLS::Stream) or DTLS (set mode to TLS::Datagram).

Parameters
modethe connection Mode
parentthe parent object for this object
providerthe name of the provider, if a specific provider is required
QCA::TLS::~TLS ( )
override

Destructor.

Member Function Documentation

int QCA::TLS::bytesAvailable ( ) const
overridevirtual

Returns the number of bytes available to be read() on the application side.

Implements QCA::SecureLayer.

int QCA::TLS::bytesOutgoingAvailable ( ) const
overridevirtual

Returns the number of bytes available to be readOutgoing() on the network side.

Implements QCA::SecureLayer.

bool QCA::TLS::canCompress ( ) const

Test if the link can use compression.

Returns
true if the link can use compression
bool QCA::TLS::canSetHostName ( ) const

Test if the link can specify a hostname (Server Name Indication)

Returns
true if the link can specify a hostname
void QCA::TLS::certificateRequested ( )
signal

Emitted when the server requests a certificate.

At this time, the client can inspect the issuerList().

You must call continueAfterStep() in order for TLS processing to resume after this signal is emitted.

This signal is only emitted in client mode.

See also
continueAfterStep
Examples:
ssltest.cpp.
int QCA::TLS::cipherBits ( ) const

The number of effective bits of security being used for this connection.

This can differ from the actual number of bits in the cipher for certain older "export ciphers" that are deliberately crippled. If you want that information, use cipherMaxBits().

Examples:
ssltest.cpp.
int QCA::TLS::cipherMaxBits ( ) const

The number of bits of security that the cipher could use.

This is normally the same as cipherBits(), but can be greater for older "export ciphers".

Examples:
ssltest.cpp.
QString QCA::TLS::cipherSuite ( ) const

The cipher suite that has been negotiated for this connection.

The name returned here is the name used in the applicable RFC (or Internet Draft, where there is no RFC).

Examples:
ssltest.cpp.
void QCA::TLS::close ( )
overridevirtual

Close the link.

Note that this may not be meaningful / possible for all implementations.

See also
isClosable() for a test that verifies if the link can be closed.

Reimplemented from QCA::SecureLayer.

bool QCA::TLS::compressionEnabled ( ) const

Returns true if compression is enabled.

This only indicates whether or not the object is configured to use compression, not whether or not the link is actually compressed. Use isCompressed() for that.

void QCA::TLS::connectNotify ( const QMetaMethod signal)
overrideprotectedvirtual

Called when a connection is made to a particular signal.

Parameters
signalthe name of the signal that has been connected to.

Reimplemented from QObject.

void QCA::TLS::continueAfterStep ( )

Resumes TLS processing.

Call this function after hostNameReceived(), certificateRequested() peerCertificateAvailable() or handshaken() is emitted. By requiring this function to be called in order to proceed, applications are given a chance to perform user interaction between steps in the TLS process.

Examples:
ssltest.cpp.
int QCA::TLS::convertBytesWritten ( qint64  encryptedBytes)
overridevirtual

Convert encrypted bytes written to plain text bytes written.

Parameters
encryptedBytesthe number of bytes to convert

Implements QCA::SecureLayer.

void QCA::TLS::disconnectNotify ( const QMetaMethod signal)
overrideprotectedvirtual

Called when a connection is removed from a particular signal.

Parameters
signalthe name of the signal that has been disconnected from.

Reimplemented from QObject.

Error QCA::TLS::errorCode ( ) const

This method returns the type of error that has occurred.

You should only need to check this if the error() signal is emitted.

Examples:
ssltest.cpp.
void QCA::TLS::handshaken ( )
signal

Emitted when the protocol handshake is complete.

At this time, all available information about the TLS session can be inspected.

You must call continueAfterStep() in order for TLS processing to resume after this signal is emitted.

See also
continueAfterStep
isHandshaken
Examples:
sslservtest.cpp, ssltest.cpp, and tlssocket.cpp.
QString QCA::TLS::hostName ( ) const

Returns the host name specified or an empty string if no host name is specified.

void QCA::TLS::hostNameReceived ( )
signal

Emitted if a host name is set by the client.

At this time, the server can inspect the hostName().

You must call continueAfterStep() in order for TLS processing to resume after this signal is emitted.

This signal is only emitted in server mode.

See also
continueAfterStep
bool QCA::TLS::isClosable ( ) const
overridevirtual

Returns true if the layer has a meaningful "close".

Reimplemented from QCA::SecureLayer.

bool QCA::TLS::isCompressed ( ) const

test if the link is compressed

Returns
true if the link is compressed
bool QCA::TLS::isHandshaken ( ) const

test if the handshake is complete

Returns
true if the handshake is complete
See also
handshaken
QList<CertificateInfoOrdered> QCA::TLS::issuerList ( ) const

Retrieve the list of allowed issuers by the server, if the server has provided them.

Only DN types will be present.

Certificate someCert = ...
PrivateKey someKey = ...
// see if the server will take our cert
CertificateInfoOrdered issuerInfo = someCert.issuerInfoOrdered().dnOnly();
foreach(const CertificateInfoOrdered &info, tls->issuerList())
{
if(info == issuerInfo)
{
// server will accept someCert, let's present it
tls->setCertificate(someCert, someKey);
break;
}
}
Examples:
ssltest.cpp.
CertificateChain QCA::TLS::localCertificateChain ( ) const

The CertificateChain for the local host certificate.

PrivateKey QCA::TLS::localPrivateKey ( ) const

The PrivateKey for the local host certificate.

int QCA::TLS::packetMTU ( ) const

Return the currently configured maximum packet size.

Note
this is only used with DTLS
int QCA::TLS::packetsAvailable ( ) const

Determine the number of packets available to be read on the application side.

Note
this is only used with DTLS.
int QCA::TLS::packetsOutgoingAvailable ( ) const

Determine the number of packets available to be read on the network side.

Note
this is only used with DTLS.
void QCA::TLS::peerCertificateAvailable ( )
signal

Emitted when a certificate is received from the peer.

At this time, you may inspect peerIdentityResult(), peerCertificateValidity(), and peerCertificateChain().

You must call continueAfterStep() in order for TLS processing to resume after this signal is emitted.

See also
continueAfterStep
CertificateChain QCA::TLS::peerCertificateChain ( ) const

The CertificateChain from the peer (other end of the connection to the trusted root certificate).

Examples:
ssltest.cpp.
Validity QCA::TLS::peerCertificateValidity ( ) const

After the SSL/TLS handshake is valid, this method allows you to check if the received certificate from the other end is valid.

As noted in peerIdentityResult(), you also need to check that the certificate matches the entity you are trying to communicate with.

Examples:
ssltest.cpp.
IdentityResult QCA::TLS::peerIdentityResult ( ) const

After the SSL/TLS handshake is complete, this method allows you to determine if the other end of the connection (if the application is a client, this is the server; if the application is a server, this is the client) has a valid identity.

Note that the security of TLS/SSL depends on checking this. It is not enough to check that the certificate is valid - you must check that the certificate is valid for the entity that you are trying to communicate with.

Note
If this returns QCA::TLS::InvalidCertificate, you may wish to use peerCertificateValidity() to determine whether to proceed or not.
Examples:
ssltest.cpp, and tlssocket.cpp.
QByteArray QCA::TLS::read ( )
overridevirtual

This method reads decrypted (plain) data from the SecureLayer implementation.

You normally call this function on the application side after receiving the readyRead() signal.

Implements QCA::SecureLayer.

Examples:
ssltest.cpp, and tlssocket.cpp.
QByteArray QCA::TLS::readOutgoing ( int *  plainBytes = nullptr)
overridevirtual

This method provides encoded (typically encrypted) data.

You normally call this function to get data to write out to the network socket (e.g. using QTcpSocket::write()) after receiving the readyReadOutgoing() signal.

Parameters
plainBytesthe number of bytes that were read.

Implements QCA::SecureLayer.

Examples:
ssltest.cpp, and tlssocket.cpp.
QByteArray QCA::TLS::readUnprocessed ( )
overridevirtual

This allows you to read data without having it decrypted first.

This is intended to be used for protocols that close off the connection and return to plain text transfer. You do not normally need to use this function.

Reimplemented from QCA::SecureLayer.

void QCA::TLS::reset ( )

Reset the connection.

Examples:
tlssocket.cpp.
TLSSession QCA::TLS::session ( ) const

The session object of the TLS connection, which can be used for resuming.

void QCA::TLS::setCertificate ( const CertificateChain cert,
const PrivateKey key 
)

The local certificate to use.

This is the certificate that will be provided to the peer. This is almost always required on the server side (because the server has to provide a certificate to the client), and may be used on the client side.

Parameters
certa chain of certificates that link the host certificate to a trusted root certificate.
keythe private key for the certificate chain
void QCA::TLS::setCertificate ( const KeyBundle kb)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Allows setting a certificate from a KeyBundle.

Parameters
kbkey bundle containing the local certificate and associated private key.
void QCA::TLS::setCompressionEnabled ( bool  b)

Set the link to use compression.

Parameters
btrue if the link should use compression, or false to disable compression
void QCA::TLS::setConstraints ( SecurityLevel  s)

The security level required for this link.

Parameters
sthe level required for this link.
void QCA::TLS::setConstraints ( int  minSSF,
int  maxSSF 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
minSSFthe minimum Security Strength Factor required for this link.
maxSSFthe maximum Security Strength Factor required for this link.
void QCA::TLS::setConstraints ( const QStringList cipherSuiteList)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
cipherSuiteLista list of the names of cipher suites that can be used for this link.
Note
the names are the same as the names in the applicable IETF RFCs (or Internet Drafts if there is no applicable RFC).
void QCA::TLS::setIssuerList ( const QList< CertificateInfoOrdered > &  issuers)

Sets the issuer list to present to the client.

For use with servers only. Only DN types are allowed.

Parameters
issuersthe list of valid issuers to be used.
void QCA::TLS::setPacketMTU ( int  size) const

Set the maximum packet size to use.

Parameters
sizethe number of bytes to set as the MTU.
Note
this is only used with DTLS.
void QCA::TLS::setSession ( const TLSSession session)

Resume a TLS session using the given session object.

Parameters
sessionthe session state to use for resumption.
void QCA::TLS::setTrustedCertificates ( const CertificateCollection trusted)

Set up the set of trusted certificates that will be used to verify that the certificate provided is valid.

Typically, this will be the collection of root certificates from the system, which you can get using QCA::systemStore(), however you may choose to pass whatever certificates match your assurance needs.

Parameters
trusteda bundle of trusted certificates.
Examples:
ssltest.cpp, and tlssocket.cpp.
void QCA::TLS::startClient ( const QString host = QString())

Start the TLS/SSL connection as a client.

Typically, you'll want to perform RFC 2818 validation on the server's certificate, based on the hostname you're intending to connect to. Pass a value for host in order to have the validation for you. If you want to bypass this behavior and do the validation yourself, pass an empty string for host.

If the host is an internationalized domain name, then it must be provided in unicode format, not in IDNA ACE/punycode format.

Parameters
hostthe hostname that you want to connect to
Note
The hostname will be used for Server Name Indication extension (see RFC 3546 Section 3.1) if supported by the backend provider.
Examples:
ssltest.cpp, and tlssocket.cpp.
void QCA::TLS::startServer ( )

Start the TLS/SSL connection as a server.

QStringList QCA::TLS::supportedCipherSuites ( const Version version = TLS_v1) const

Get the list of cipher suites that are available for use.

A cipher suite is a combination of key exchange, encryption and hashing algorithms that are agreed during the initial handshake between client and server.

Parameters
versionthe protocol Version that the cipher suites are required for
Returns
list of the names of the cipher suites supported.
CertificateCollection QCA::TLS::trustedCertificates ( ) const

Return the trusted certificates set for this object.

Version QCA::TLS::version ( ) const

The protocol version that is in use for this connection.

void QCA::TLS::write ( const QByteArray a)
overridevirtual

This method writes unencrypted (plain) data to the SecureLayer implementation.

You normally call this function on the application side.

Parameters
athe source of the application-side data

Implements QCA::SecureLayer.

Examples:
ssltest.cpp, and tlssocket.cpp.
void QCA::TLS::writeIncoming ( const QByteArray a)
overridevirtual

This method accepts encoded (typically encrypted) data for processing.

You normally call this function using data read from the network socket (e.g. using QTcpSocket::readAll()) after receiving a signal that indicates that the socket has data to read.

Parameters
athe ByteArray to take network-side data from

Implements QCA::SecureLayer.

Examples:
ssltest.cpp, and tlssocket.cpp.

The documentation for this class was generated from the following file:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 6 2020 23:02:40 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.