QCA::TLS Class Reference

Transport Layer Security / Secure Socket Layer. More...

#include <QtCrypto>

Inheritance diagram for QCA::TLS:

QCA::SecureLayer QCA::Algorithm QObject Collaboration diagram for QCA::TLS:

Collaboration graph
[legend]
List of all members.

Public Types

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

Public Member Functions

 TLS (QObject *parent=0, const QString &provider=QString())
 TLS (Mode mode, QObject *parent=0, const QString &provider=QString())
 ~TLS ()
void reset ()
QStringList supportedCipherSuites (const Version &version=TLS_v1) const
void setCertificate (const CertificateChain &cert, const PrivateKey &key)
void setCertificate (const KeyBundle &kb)
CertificateCollection trustedCertificates () const
void setTrustedCertificates (const CertificateCollection &trusted)
void setConstraints (SecurityLevel s)
void setConstraints (int minSSF, int maxSSF)
void setConstraints (const QStringList &cipherSuiteList)
QList< CertificateInfoOrderedissuerList () const
void setIssuerList (const QList< CertificateInfoOrdered > &issuers)
void setSession (const TLSSession &session)
bool canCompress () const
bool canSetHostName () const
bool compressionEnabled () const
void setCompressionEnabled (bool b)
QString hostName () const
void startClient (const QString &host=QString())
void startServer ()
void continueAfterStep ()
bool isHandshaken () const
bool isCompressed () const
Version version () const
QString cipherSuite () const
int cipherBits () const
int cipherMaxBits () const
TLSSession session () const
Error errorCode () const
IdentityResult peerIdentityResult () const
Validity peerCertificateValidity () const
CertificateChain localCertificateChain () const
PrivateKey localPrivateKey () const
CertificateChain peerCertificateChain () const
virtual bool isClosable () const
virtual int bytesAvailable () const
virtual int bytesOutgoingAvailable () const
virtual void close ()
virtual void write (const QByteArray &a)
virtual QByteArray read ()
virtual void writeIncoming (const QByteArray &a)
virtual QByteArray readOutgoing (int *plainBytes=0)
virtual QByteArray readUnprocessed ()
virtual int convertBytesWritten (qint64 encryptedBytes)
int packetsAvailable () const
int packetsOutgoingAvailable () const
int packetMTU () const
void setPacketMTU (int size) const
void certificateRequested ()
void handshaken ()

Public Attributes

Q_SIGNALS __pad0__: void hostNameReceived()

Protected Member Functions

void connectNotify (const char *signal)
void disconnectNotify (const char *signal)

Friends

class Private

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


Member Enumeration Documentation

enum QCA::TLS::Mode
 

Operating mode.

Enumerator:
Stream  stream mode
Datagram  datagram mode

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.

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

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


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

QCA::TLS::TLS Mode  mode,
QObject parent = 0,
const QString provider = QString()
[explicit]
 

Constructor for Transport Layer Security connection.

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

QCA::TLS::~TLS  ) 
 

Destructor.


Member Function Documentation

void QCA::TLS::reset  ) 
 

Reset the connection.

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.

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

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.

CertificateCollection QCA::TLS::trustedCertificates  )  const
 

Return the trusted certificates set for this object.

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.
Examples:
ssltest.cpp.

void QCA::TLS::setConstraints SecurityLevel  s  ) 
 

The security level required for this link.

Parameters:
s the 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:
minSSF the minimum Security Strength Factor required for this link.
maxSSF the 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:
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).

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.

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.

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

Resume a TLS session using the given session object.

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

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::setCompressionEnabled bool  b  ) 
 

Set the link to use compression.

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

QString QCA::TLS::hostName  )  const
 

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

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.
Examples:
ssltest.cpp.

void QCA::TLS::startServer  ) 
 

Start the TLS/SSL connection as a server.

void QCA::TLS::continueAfterStep  ) 
 

Resumes TLS processing.

Call this function after hostNameReceived(), certificateRequested() 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.

bool QCA::TLS::isHandshaken  )  const
 

test if the handshake is complete

Returns:
true if the handshake is complete
See also:
handshaken

bool QCA::TLS::isCompressed  )  const
 

test if the link is compressed

Returns:
true if the link is compressed

Version QCA::TLS::version  )  const
 

The protocol version that is in use for this connection.

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.

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.

TLSSession QCA::TLS::session  )  const
 

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

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.

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.

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.

CertificateChain QCA::TLS::localCertificateChain  )  const
 

The CertificateChain for the local host certificate.

PrivateKey QCA::TLS::localPrivateKey  )  const
 

The PrivateKey for the local host certificate.

CertificateChain QCA::TLS::peerCertificateChain  )  const
 

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

Examples:
ssltest.cpp.

virtual bool QCA::TLS::isClosable  )  const [virtual]
 

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

Reimplemented from QCA::SecureLayer.

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

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

Implements QCA::SecureLayer.

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

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

Implements QCA::SecureLayer.

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

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

Implements QCA::SecureLayer.

Examples:
ssltest.cpp.

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

Examples:
ssltest.cpp.

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

Implements QCA::SecureLayer.

Examples:
ssltest.cpp.

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

Implements QCA::SecureLayer.

Examples:
ssltest.cpp.

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

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

Convert encrypted bytes written to plain text bytes written.

Implements QCA::SecureLayer.

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.

int QCA::TLS::packetMTU  )  const
 

Return the currently configured maximum packet size.

Note:
this is only used with DTLS

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.

void QCA::TLS::certificateRequested  ) 
 

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

void QCA::TLS::handshaken  ) 
 

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


The documentation for this class was generated from the following file:
Generated on Fri Jul 6 12:15:33 2007 for Qt Cryptographic Architecture by  doxygen 1.4.6