| Home | |
The QtSSLSocket class provides a socket with SSL encryption support. More...
#include <qtsslsocket.h>
The QtSSLSocket class provides a socket with SSL encryption support.
It provides some extra functionality which is needed for working with SSL, but otherwise there is no difference from QSocket. Example:
void MyClient::connectToHost(const QString &host, int port)
{
// Create a new SSL socket
socket = new QtSSLSocket();
// Set the path to the CA certificates
socket->setPathToCACertDir("/etc/ssl/certs/");
// Connect the socket's signals to slots in our client
// implementation.
connect(socket, SIGNAL(connected()), SLOT(connectedToHost()));
connect(socket, SIGNAL(readyRead()), SLOT(readData()));
connect(socket, SIGNAL(connectionClosed()), SLOT(connectionClosed()));
connect(socket, SIGNAL(error(int)), SLOT(inspectError(int)));
connect(socket, SIGNAL(certCheckFailed(int, const QString &)),
SLOT(checkCertError(int, const QString &)));
// Initiate a connection.
socket->connectToHost(host, port);
}
Use connectToHost() when connecting to an SSL server. This will eventually emit the connected() signal if the connection was established, or the error(int) signal if the connection failed.
An alternative approach is to call connectToHost() on a QSocket, and when the socket's connected() signal is emitted, pass the socket to a QtSSLSocket via the constructor. If you use this approach, you must call QtSSLSocket::sslConnect() explicitly to initiate the client side SSL handshake; QtSSLSocket's connected() signal is emitted when the SSL link is established.
In the case of accepting incoming connections, it is common practice to create a subclass of QServerSocket and to reimplement QServerSocket::newConnection(). In newConnection(), a QSSLSocket is created, setSocket() is called, and QtSSLSocket's signals accepted(), readyRead(), connectionClosed(), delayedCloseFinished() and error(int) are connected to slots in the server class. The path to a file containing a PEM encoded certificate is set with setPathToCertificate(). The path to the private key file is set with setPathToPrivateKey(). Finally, to prepare for the client's SSL handshake, sslAccept() is called. When QtSSLSocket emits accepted(), the SSL encrypted link is established. Example:
void MyServer::newConnection(int socket)
{
// Create a new socket and pass it a new QSocket
socket = new QtSSLSocket(QtSSLSocket::Server);
socket->setSocket(new QSocket(socket));
// Set up the certificate and private key.
socket->setPathToCertificate("/etc/ssl/servercert.pem");
socket->setPathToPrivateKey("/etc/ssl/serverkey.pem");
// Connect the socket's signals to slots in our server
// implementation
connect(socket, SIGNAL(accepted()), SLOT(acceptedClient()));
connect(socket, SIGNAL(connectionClosed()), SLOT(connectionClosed()));
connect(socket, SIGNAL(readyRead()), SLOT(readData()));
connect(socket, SIGNAL(error(int)), SLOT(error(int)));
// Initiate SSL handshake.
socket->sslAccept();
}
Most often clients, but sometimes also servers need a set of certificate authority (CA) certificates to verify the identity of their peer. Use setPathToCACertFile() and setPathToCACertDir() for this. Sometimes, it is useful to restrict the encryption ciphers available to the client or server with setCiphers().
As mentioned, QtSSLSocket emits connected() when the connection has been established and the SSL handshake has been completed. Make sure to connect to error() and certCheckFailed() to catch errors. The readyRead() signal is emitted when there is new incoming data. Call readBlock() to read the new data into a buffer. For server implementations, the accepted() signal is emitted when the SSL handshake has been completed with an incoming client connection. When connectionClosed() is emitted, the other peer has closed the connection. If there is pending data that has not been written to the peer when close() is called, the delayedCloseFinished() signal will be emitted after the data was written and the connection was closed.
If certCheckFailed() is emitted, it is often useful to display details about the failing certificate to the user. peerCertificate() returns information about this certificate. To get the local certificate, call localCertificate().
When building an application that uses QtSSLSocket, you must link your application against the SSL library. Include the bundled .pri file, or add the following line to your .pro file, modified with the path to your installation of OpenSSL:
unix:LIBS += -L/usr/lib -lssl -lcrypto
win32:INCLUDEPATH += /openssl/include
win32:LIBS += -L/openssl/lib ssleay32.lib libeay32.lib
The pri file must be edited to set the paths of the SSL files.
Note: QtSSLSocket requires OpenSSL. The OpenSSL toolkit is licensed under an Apache-style licence, which basically means that you are free to get and use it for commercial and non-commercial purposes subject to certain license conditions. The official web site is: http://www.openssl.org/ . Windows binaries are available from: http://www.openssl.org/related/binaries.html .
See also QSocket and QServerSocket.
This enum describes the different error codes emitted through the signal error(). All error codes describe a state in which it is impossible to continue communication on the existing link.
Calling errorString() immediately after the error() signal is emitted will give more information about the error condition.
This enum describes the two modes QtSSLSocket can run in.
This enum describes the different states the SSL socket can be in:
This enum describes the results of the peer certificate verification process. If the certificate check fails for some reason, the certCheckFailed() signal is emitted and one of the following results will be passed:
errorString() will give a more detailed description of the actual error that occurred.
The parent and name arguments are passed to QObject's constructor.
When in server mode, this signal is emitted when the SSL link is estalished. It is then safe to call readBlock() and writeBlock().
Example: sslserver.cpp.
Warning: QSocket::bytesAvailable() is not virtual. In order to get a reliable return value from this function, a QtSSLSocket pointer or reference must be used.
Notice that QSocket::canReadLine() is non-virtual, so this function does not work polymorphically (i.e., calling this function on a QSocket* pointer will call QSocket::canReadLine() and not QtSSLSocket::canReadLine()). When operating on a QSocket* pointer, you must call readBlock() or readAll() instead.
See also readLine().
This signal is emitted if there was an error when verifying the identity of the peer. There can be many reasons for this, among others that the peer's SSL certificate has expired, that the peer uses a self-signed certificate and that there are problems with the certificate authorities.
code is of the type VerifyResult, and can be checked to determine the reason for the failure. description contains a human readable description of the cause of the error.
Example: sslclient.cpp.
Example: sslserver.cpp.
QtSSLSocket will emit connected() or error(), depending on the result of the connection attempt.
If during the SSL handshake there was an error with verifying the identity of the server host, certCheckFailed() is emitted.
Examples: sslclient.cpp and sslserver.cpp.
Example: sslserver.cpp.
The certificate is encoded as a sequence of key-value pairs delimited by the '/' character. The keys and values are delimited with '='.
See also peerCertificate().
See also setPathToCACertDir() and setPathToCACertFile().
See also setPathToCACertFile().
The certificate is encoded as a sequence of key-value pairs delimited by the '/' character. The keys and values are delimited with '='.
See also localCertificate().
Example: sslclient.cpp.
Example: sslserver.cpp.
Returns the number of unencrypted bytes read, or 0 if there was no more data to read. This function is usually called after the readyRead() signal is emitted.
See also readyRead() and bytesAvailable().
See also canReadLine().
Read more about the format of the input string ciph in the OpenSSL cipher documentation: http://www.openssl.org/docs/apps/ciphers.html
This is useful if the server has one or more files with the root CA certificates that came with the operating system, in addition to several self-created unofficial CA certificates.
The certificates in the CA certificate file are used before those in the CA certificate directory.
See also setPathToCACertFile() and pathToCACertDir().
Examples: sslclient.cpp and sslserver.cpp.
Use setPAthToCACertDir() if there is need to use more than one CA certificate.
See also pathToCACertFile() and setPathToCACertDir().
Calling this function is necessary when running QtSSLSocket in Server mode. Clients do not call this function.
The file, which must be readable by the server application, is used internally to negotiate an SSL connection. For more information on how to generate such files see the official OpenSSL FAQ at: http://www.openssl.org/support/faq.html.
See also pathToCertificate() and setPathToPrivateKey().
Example: sslserver.cpp.
Calling this function is necessary when running QtSSLSocket in Server mode. Clients do not call this function.
The file, which must be readable by the server application, is used internally to negotiate an SSL connection. For more information on how to generate such files see the official OpenSSL FAQ at: http://www.openssl.org/support/faq.html.
See also pathToPrivateKey() and setPathToCertificate().
Example: sslserver.cpp.
Example: sslserver.cpp.
Example: sslserver.cpp.
See also QtSSLSocket::State.
The data is dispatched immediately, but it may take some time before the data is received by the remote peer.
Returns the number of bytes written, or -1 if an error occurred.
Example: sslserver.cpp.
This file is part of the Qt Solutions.
Copyright © 2003-2006
Trolltech. All Rights Reserved.
| Copyright © 2003-2006 Trolltech | Trademarks | Qt Solutions
|