qca

QCA::TLS

QCA::TLS Class Reference
[QCA user API]

#include <QtCrypto>

Inheritance diagram for QCA::TLS:

[legend]

List of all members.

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.

Definition at line 289 of file qca_securelayer.h.


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 ()
Public Member Functions
virtual int	bytesAvailable () const
virtual int	bytesOutgoingAvailable () const
bool	canCompress () const
bool	canSetHostName () const
int	cipherBits () const
int	cipherMaxBits () const
QString	cipherSuite () const
virtual void	close ()
bool	compressionEnabled () const
void	continueAfterStep ()
virtual int	convertBytesWritten (qint64 encryptedBytes)
Error	errorCode () const
QString	hostName () const
virtual bool	isClosable () const
bool	isCompressed () const
bool	isHandshaken () const
QList< CertificateInfoOrdered >	issuerList () 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
virtual QByteArray	read ()
virtual QByteArray	readOutgoing (int *plainBytes=0)
virtual QByteArray	readUnprocessed ()
void	reset ()
TLSSession	session () const
void	setCertificate (const KeyBundle &kb)
void	setCertificate (const CertificateChain &cert, const PrivateKey &key)
void	setCompressionEnabled (bool b)
void	setConstraints (const QStringList &cipherSuiteList)
void	setConstraints (int minSSF, int maxSSF)
void	setConstraints (SecurityLevel s)
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
	TLS (Mode mode, QObject *parent=0, const QString &provider=QString())
	TLS (QObject *parent=0, const QString &provider=QString())
CertificateCollection	trustedCertificates () const
Version	version () const
virtual void	write (const QByteArray &a)
virtual void	writeIncoming (const QByteArray &a)
	~TLS ()
Protected Member Functions
void	connectNotify (const char *signal)
void	disconnectNotify (const char *signal)

Member Enumeration Documentation

enum QCA::TLS::Error

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.

enum QCA::TLS::IdentityResult

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.

enum QCA::TLS::Mode

Operating mode.

Enumerator:

Stream	stream mode
Datagram	datagram mode

Definition at line 296 of file qca_securelayer.h.

enum QCA::TLS::Version

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 = `0`,
		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:

	parent	the parent object for this object
	provider	the name of the provider, if a specific provider is required

Definition at line 798 of file qca_securelayer.cpp.

QCA::TLS::TLS	(	Mode	mode,
		QObject *	parent = `0`,
		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:

	mode	the connection Mode
	parent	the parent object for this object
	provider	the name of the provider, if a specific provider is required

Definition at line 804 of file qca_securelayer.cpp.

QCA::TLS::~TLS ( )

Destructor.

Definition at line 810 of file qca_securelayer.cpp.

Member Function Documentation

int QCA::TLS::bytesAvailable ( ) const [virtual]

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

Implements QCA::SecureLayer.

Definition at line 1044 of file qca_securelayer.cpp.

int QCA::TLS::bytesOutgoingAvailable ( ) const [virtual]

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

Implements QCA::SecureLayer.

Definition at line 1052 of file qca_securelayer.cpp.

bool QCA::TLS::canCompress ( ) const

Test if the link can use compression.

Returns:: true if the link can use compression

Definition at line 919 of file qca_securelayer.cpp.

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

Definition at line 924 of file qca_securelayer.cpp.

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

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().

Definition at line 985 of file qca_securelayer.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".

Definition at line 990 of file qca_securelayer.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).

Definition at line 980 of file qca_securelayer.cpp.

void QCA::TLS::close ( ) [virtual]

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.

Definition at line 1060 of file qca_securelayer.cpp.

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.

Definition at line 929 of file qca_securelayer.cpp.

void QCA::TLS::connectNotify ( const char * signal ) [protected]

Called when a connection is made to a particular signal.

Parameters:

signal

the name of the signal that has been connected to.

Reimplemented from QObject.

Definition at line 1176 of file qca_securelayer.cpp.

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.

Definition at line 957 of file qca_securelayer.cpp.

int QCA::TLS::convertBytesWritten ( qint64 encryptedBytes ) [virtual]

Convert encrypted bytes written to plain text bytes written.

Parameters:

encryptedBytes

the number of bytes to convert

Implements QCA::SecureLayer.

Definition at line 1149 of file qca_securelayer.cpp.

void QCA::TLS::disconnectNotify ( const char * signal ) [protected]

Called when a connection is removed from a particular signal.

Parameters:

signal

the name of the signal that has been disconnected from.

Reimplemented from QObject.

Definition at line 1188 of file qca_securelayer.cpp.

TLS::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.

Definition at line 1000 of file qca_securelayer.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

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 [virtual]

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

Reimplemented from QCA::SecureLayer.

Definition at line 1039 of file qca_securelayer.cpp.

bool QCA::TLS::isCompressed ( ) const

test if the link is compressed

Returns:: true if the link is compressed

Definition at line 970 of file qca_securelayer.cpp.

bool QCA::TLS::isHandshaken ( ) const

test if the handshake is complete

Returns:: true if the handshake is complete

See also:: handshaken

Definition at line 962 of file qca_securelayer.cpp.

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;
    }
}

Definition at line 902 of file qca_securelayer.cpp.

CertificateChain QCA::TLS::localCertificateChain ( ) const

The CertificateChain for the local host certificate.

Definition at line 1024 of file qca_securelayer.cpp.

PrivateKey QCA::TLS::localPrivateKey ( ) const

The PrivateKey for the local host certificate.

Definition at line 1029 of file qca_securelayer.cpp.

int QCA::TLS::packetMTU ( ) const

Return the currently configured maximum packet size.

Note:: this is only used with DTLS

Definition at line 1164 of file qca_securelayer.cpp.

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.

Definition at line 1154 of file qca_securelayer.cpp.

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.

Definition at line 1159 of file qca_securelayer.cpp.

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).

Definition at line 1034 of file qca_securelayer.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.

Definition at line 1019 of file qca_securelayer.cpp.

TLS::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.

Definition at line 1005 of file qca_securelayer.cpp.

QByteArray QCA::TLS::read ( ) [virtual]

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.

Definition at line 1079 of file qca_securelayer.cpp.

QByteArray QCA::TLS::readOutgoing ( int * plainBytes = 0 ) [virtual]

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:

plainBytes

the number of bytes that were read.

Implements QCA::SecureLayer.

Definition at line 1106 of file qca_securelayer.cpp.

QByteArray QCA::TLS::readUnprocessed ( ) [virtual]

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.

Definition at line 1137 of file qca_securelayer.cpp.

void QCA::TLS::reset ( )

Reset the connection.

Definition at line 815 of file qca_securelayer.cpp.

TLSSession QCA::TLS::session ( ) const

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

Definition at line 995 of file qca_securelayer.cpp.

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:

key bundle containing the local certificate and associated private key.

Definition at line 833 of file qca_securelayer.cpp.

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:

	cert	a chain of certificates that link the host certificate to a trusted root certificate.
	key	the private key for the certificate chain

Definition at line 825 of file qca_securelayer.cpp.

void QCA::TLS::setCompressionEnabled ( bool b )

Set the link to use compression.

Parameters:

true if the link should use compression, or false to disable compression

Definition at line 934 of file qca_securelayer.cpp.

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:

cipherSuiteList

a 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).

Definition at line 893 of file qca_securelayer.cpp.

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:

	minSSF	the minimum Security Strength Factor required for this link.
	maxSSF	the maximum Security Strength Factor required for this link.

Definition at line 883 of file qca_securelayer.cpp.

void QCA::TLS::setConstraints ( SecurityLevel s )

The security level required for this link.

Parameters:

the level required for this link.

Definition at line 850 of file qca_securelayer.cpp.

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:

issuers

the list of valid issuers to be used.

Definition at line 907 of file qca_securelayer.cpp.

void QCA::TLS::setPacketMTU ( int size ) const

Set the maximum packet size to use.

Parameters:

size

the number of bytes to set as the MTU.

Note:: this is only used with DTLS.

Definition at line 1169 of file qca_securelayer.cpp.

void QCA::TLS::setSession ( const TLSSession & session )

Resume a TLS session using the given session object.

Parameters:

session

the session state to use for resumption.

Definition at line 914 of file qca_securelayer.cpp.

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:

trusted

a bundle of trusted certificates.

Definition at line 843 of file qca_securelayer.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:

host

the 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.

Definition at line 939 of file qca_securelayer.cpp.

void QCA::TLS::startServer ( )

Start the TLS/SSL connection as a server.

Definition at line 949 of file qca_securelayer.cpp.

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:

version

the protocol Version that the cipher suites are required for

Returns:: list of the the names of the cipher suites supported.

Definition at line 820 of file qca_securelayer.cpp.

CertificateCollection QCA::TLS::trustedCertificates ( ) const

Return the trusted certificates set for this object.

Definition at line 838 of file qca_securelayer.cpp.

TLS::Version QCA::TLS::version ( ) const

The protocol version that is in use for this connection.

Definition at line 975 of file qca_securelayer.cpp.

void QCA::TLS::write ( const QByteArray & a ) [virtual]

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

You normally call this function on the application side.

Parameters:

the source of the application-side data

Implements QCA::SecureLayer.

Definition at line 1066 of file qca_securelayer.cpp.

void QCA::TLS::writeIncoming ( const QByteArray & a ) [virtual]

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:

the ByteArray to take network-side data from

Implements QCA::SecureLayer.

Definition at line 1096 of file qca_securelayer.cpp.

The documentation for this class was generated from the following files:

qca

QCA::TLS Class Reference [QCA user API]

Detailed Description

Public Types

Signals

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

qca

API Reference

QCA::TLS Class Reference
[QCA user API]