|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.QSignalEmitter
com.trolltech.qt.QtJambiObject
com.trolltech.qt.core.QObject
com.trolltech.qt.core.QIODevice
com.trolltech.qt.network.QAbstractSocket
com.trolltech.qt.network.QTcpSocket
com.trolltech.qt.network.QSslSocket
public class QSslSocket
The QSslSocket class provides an SSL encrypted socket for both clients and servers. QSslSocket establishes a secure, encrypted TCP connection you can use for transmitting encrypted data. It can operate in both client and server mode, and it supports modern SSL protocols, including SSLv3 and TLSv1. By default, QSslSocket uses SSLv3, but you can change the SSL protocol by calling setProtocol()
as long as you do it before the handshake has started.
SSL encryption operates on top of the existing TCP stream after the socket enters the ConnectedState
. There are two simple ways to establish a secure connection using QSslSocket: With an immediate SSL handshake, or with a delayed SSL handshake occurring after the connection has been established in unencrypted mode.
The most common way to use QSslSocket is to construct an object and start a secure connection by calling connectToHostEncrypted()
. This method starts an immediate SSL handshake once the connection has been established.
The following code example is written in c++.
QSslSocket *socket = new QSslSocket(this); connect(socket, SIGNAL(encrypted()), this, SLOT(ready())); socket->connectToHostEncrypted("imap.example.com", 993);As with a plain
QTcpSocket
, QSslSocket enters the HostLookupState
, ConnectingState
, and finally the ConnectedState
, if the connection is successful. The handshake then starts automatically, and if it succeeds, the encrypted()
signal is emitted to indicate the socket has entered the encrypted state and is ready for use. Note that data can be written to the socket immediately after the return from connectToHostEncrypted()
(i.e., before the encrypted()
signal is emitted). The data is queued in QSslSocket until after the encrypted()
signal is emitted.
An example of using the delayed SSL handshake to secure an existing connection is the case where an SSL server secures an incoming connection. Suppose you create an SSL server class as a subclass of QTcpServer
. You would override QTcpServer::incomingConnection()
with something like the example below, which first constructs an instance of QSslSocket and then calls setSocketDescriptor()
to set the new socket's descriptor to the existing one passed in. It then initiates the SSL handshake by calling startServerEncryption()
.
The following code example is written in c++.
void SslServer::incomingConnection(int socketDescriptor) { QSslSocket *serverSocket = new QSslSocket; if (serverSocket->setSocketDescriptor(socketDescriptor)) { connect(serverSocket, SIGNAL(encrypted()), this, SLOT(ready())); serverSocket->startServerEncryption(); } else { delete serverSocket; } }If an error occurs, QSslSocket emits the
sslErrors()
signal. In this case, if no action is taken to ignore the error(s), the connection is dropped. To continue, despite the occurrence of an error, you can call ignoreSslErrors()
, either from within this slot after the error occurs, or any time after construction of the QSslSocket and before the connection is attempted. This will allow QSslSocket to ignore the errors it encounters when establishing the identity of the peer. Ignoring errors during an SSL handshake should be used with caution, since a fundamental characteristic of secure connections is that they should be established with a successful handshake. Once encrypted, you use QSslSocket as a regular QTcpSocket
. When readyRead()
is emitted, you can call read()
, canReadLine()
and readLine()
, or getChar() to read decrypted data from QSslSocket's internal buffer, and you can call write()
or putChar() to write data back to the peer. QSslSocket will automatically encrypt the written data for you, and emit bytesWritten()
once the data has been written to the peer.
As a convenience, QSslSocket supports QTcpSocket
's blocking functions waitForConnected(), waitForReadyRead()
, waitForBytesWritten()
, and waitForDisconnected(). It also provides waitForEncrypted()
, which will block the calling thread until an encrypted connection has been established.
The following code example is written in c++.
QSslSocket socket; socket.connectToHostEncrypted("http.example.com", 443); if (!socket.waitForEncrypted()) { qDebug() << socket.errorString(); return false; } socket.write("GET / HTTP/1.0\r\n\r\n"); while (socket.waitForReadyRead()) qDebug() << socket.readAll().data();QSslSocket provides an extensive, easy-to-use API for handling cryptographic ciphers, private keys, and local, peer, and Certification Authority (CA) certificates. It also provides an API for handling errors that occur during the handshake phase.
The following features can also be customized:
setCiphers()
and setDefaultCiphers()
.setLocalCertificate()
and setPrivateKey()
.addCaCertificate()
, addCaCertificates()
, setCaCertificates()
, addDefaultCaCertificate()
, addDefaultCaCertificates()
, and setDefaultCaCertificates()
.QSslCipher
and QSslCertificate
. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
QSslCertificate
, QSslCipher
, and QSslError
.
Nested Class Summary | |
---|---|
static class |
QSslSocket.PeerVerifyMode
Describes the peer verification modes for QSslSocket . |
static class |
QSslSocket.SslMode
Describes the connection modes available for QSslSocket . |
Nested classes/interfaces inherited from class com.trolltech.qt.network.QAbstractSocket |
---|
QAbstractSocket.NetworkLayerProtocol, QAbstractSocket.SocketError, QAbstractSocket.SocketState, QAbstractSocket.SocketType |
Nested classes/interfaces inherited from class com.trolltech.qt.core.QIODevice |
---|
QIODevice.OpenMode, QIODevice.OpenModeFlag |
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal |
---|
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal |
Field Summary | |
---|---|
QSignalEmitter.Signal0 |
encrypted
This signal is emitted when QSslSocket enters encrypted mode. |
QSignalEmitter.Signal1 |
encryptedBytesWritten
This signal takes 1 generic argument(s). |
QSignalEmitter.Signal1 |
modeChanged
This signal takes 1 generic argument(s). |
QSignalEmitter.Signal1 |
peerVerifyError
This signal takes 1 generic argument(s). |
QSignalEmitter.Signal1 |
sslErrors
This signal takes 1 generic argument(s). |
Fields inherited from class com.trolltech.qt.network.QAbstractSocket |
---|
connected, disconnected, error, hostFound, proxyAuthenticationRequired, stateChanged |
Fields inherited from class com.trolltech.qt.core.QIODevice |
---|
aboutToClose, bytesWritten, readChannelFinished, readyRead |
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal |
---|
currentSender |
Constructor Summary | |
---|---|
QSslSocket()
Constructs a QSslSocket object. |
|
QSslSocket(QObject parent)
Constructs a QSslSocket object. |
Method Summary | |
---|---|
void |
addCaCertificate(QSslCertificate certificate)
Adds the certificate to this socket's CA certificate database. |
void |
addCaCertificates(java.util.List certificates)
Adds the certificates to this socket's CA certificate database. |
boolean |
addCaCertificates(java.lang.String path)
Searches all files in the path for certificates encoded in the specified format and adds them to this socket's CA certificate database. |
boolean |
addCaCertificates(java.lang.String path,
QSsl.EncodingFormat format)
Searches all files in the path for certificates encoded in the specified format and adds them to this socket's CA certificate database. |
boolean |
addCaCertificates(java.lang.String path,
QSsl.EncodingFormat format,
QRegExp.PatternSyntax syntax)
Searches all files in the path for certificates encoded in the specified format and adds them to this socket's CA certificate database. |
static void |
addDefaultCaCertificate(QSslCertificate certificate)
Adds certificate to the default CA certificate database. |
static void |
addDefaultCaCertificates(java.util.List certificates)
Adds certificates to the default CA certificate database. |
static boolean |
addDefaultCaCertificates(java.lang.String path)
Searches all files in the path for certificates with the specified encoding and adds them to the default CA certificate database. |
static boolean |
addDefaultCaCertificates(java.lang.String path,
QSsl.EncodingFormat format)
Searches all files in the path for certificates with the specified encoding and adds them to the default CA certificate database. |
static boolean |
addDefaultCaCertificates(java.lang.String path,
QSsl.EncodingFormat format,
QRegExp.PatternSyntax syntax)
Searches all files in the path for certificates with the specified encoding and adds them to the default CA certificate database. |
java.util.List |
caCertificates()
Returns this socket's CA certificate database. |
java.util.List |
ciphers()
Returns this socket's current cryptographic cipher suite. |
void |
connectToHostEncrypted(java.lang.String hostName,
char port)
|
void |
connectToHostEncrypted(java.lang.String hostName,
char port,
QIODevice.OpenMode mode)
|
void |
connectToHostEncrypted(java.lang.String hostName,
char port,
QIODevice.OpenModeFlag[] mode)
|
protected void |
connectToHostImplementation(java.lang.String host,
int port)
This method is internal to Qt Jambi. |
protected void |
connectToHostImplementation(java.lang.String host,
int port,
QIODevice.OpenMode mode)
This method is internal to Qt Jambi. |
protected void |
connectToHostImplementation(java.lang.String host,
int port,
QIODevice.OpenModeFlag[] mode)
This method is internal to Qt Jambi. |
static java.util.List |
defaultCaCertificates()
Returns the current default CA certificate database. |
static java.util.List |
defaultCiphers()
Returns the default cryptographic cipher suite for all sockets in this application. |
long |
encryptedBytesAvailable()
Returns the number of encrypted bytes that are awaiting decryption. |
long |
encryptedBytesToWrite()
Returns the number of encrypted bytes that are waiting to be written to the network. |
void |
ignoreSslErrors()
This slot tells QSslSocket to ignore errors during QSslSocket's handshake phase and continue connecting. |
boolean |
isEncrypted()
Returns true if the socket is encrypted; otherwise, false is returned. |
QSslCertificate |
localCertificate()
Returns the socket's local certificate , or an empty certificate if no local certificate has been assigned. |
QSslSocket.SslMode |
mode()
Returns the current mode for the socket; either UnencryptedMode , where QSslSocket behaves identially to QTcpSocket , or one of SslClientMode or SslServerMode , where the client is either negotiating or in encrypted mode. |
QSslCertificate |
peerCertificate()
Returns the peer's digital certificate (i. |
java.util.List |
peerCertificateChain()
Returns the peer's chain of digital certificates, or an empty list of certificates. |
int |
peerVerifyDepth()
Returns the maximum number of certificates in the peer's certificate chain to be checked during the SSL handshake phase, or 0 (the default) if no maximum depth has been set, indicating that the whole certificate chain should be checked. |
QSslSocket.PeerVerifyMode |
peerVerifyMode()
Returns the socket's verify mode. |
QSslKey |
privateKey()
Returns this socket's private key. |
QSsl.SslProtocol |
protocol()
Returns the socket's SSL protocol. |
QSslCipher |
sessionCipher()
Returns the socket's cryptographic cipher , or a null cipher if the connection isn't encrypted. |
void |
setCaCertificates(java.util.List certificates)
Sets this socket's CA certificate database to be certificates. |
void |
setCiphers(java.util.List ciphers)
Sets the cryptographic cipher suite for this socket to ciphers, which must contain a subset of the ciphers in the list returned by supportedCiphers() . |
void |
setCiphers(java.lang.String ciphers)
Sets the cryptographic cipher suite for this socket to ciphers, which is a colon-separated list of cipher suite names. |
static void |
setDefaultCaCertificates(java.util.List certificates)
Sets the default CA certificate database to certificates. |
static void |
setDefaultCiphers(java.util.List ciphers)
Sets the default cryptographic cipher suite for all sockets in this application to ciphers, which must contain a subset of the ciphers in the list returned by supportedCiphers() . |
void |
setLocalCertificate(QSslCertificate certificate)
Sets the socket's local certificate to certificate. |
void |
setLocalCertificate(java.lang.String fileName)
This is an overloaded member function, provided for convenience. |
void |
setLocalCertificate(java.lang.String fileName,
QSsl.EncodingFormat format)
This is an overloaded member function, provided for convenience. |
void |
setPeerVerifyDepth(int depth)
Sets the maximum number of certificates in the peer's certificate chain to be checked during the SSL handshake phase, to depth. |
void |
setPeerVerifyMode(QSslSocket.PeerVerifyMode mode)
Sets the socket's verify mode to mode. |
void |
setPrivateKey(QSslKey key)
Sets the socket's private key to key. |
void |
setPrivateKey(java.lang.String fileName)
This is an overloaded member function, provided for convenience. |
void |
setPrivateKey(java.lang.String fileName,
QSsl.KeyAlgorithm algorithm)
This is an overloaded member function, provided for convenience. |
void |
setPrivateKey(java.lang.String fileName,
QSsl.KeyAlgorithm algorithm,
QSsl.EncodingFormat format)
This is an overloaded member function, provided for convenience. |
void |
setPrivateKey(java.lang.String fileName,
QSsl.KeyAlgorithm algorithm,
QSsl.EncodingFormat format,
QByteArray passPhrase)
This is an overloaded member function, provided for convenience. |
void |
setProtocol(QSsl.SslProtocol protocol)
Sets the socket's SSL protocol to protocol. |
boolean |
setSocketDescriptor(int socketDescriptor,
QAbstractSocket.SocketState state,
QIODevice.OpenMode openMode)
Initializes QSslSocket with the native socket descriptor socketDescriptor. |
void |
setSslConfiguration(QSslConfiguration config)
Sets the socket's SSL configuration to be the contents of configuration. |
QSslConfiguration |
sslConfiguration()
Returns the socket's SSL configuration state. |
java.util.List |
sslErrors()
Returns a list of the last SSL errors that occurred. |
void |
startClientEncryption()
Starts a delayed SSL handshake for a client connection. |
void |
startServerEncryption()
Starts a delayed SSL handshake for a server connection. |
static java.util.List |
supportedCiphers()
Returns the list of cryptographic ciphers supported by this system. |
static boolean |
supportsSsl()
Returns true if this platform supports SSL; otherwise, returns false. |
static java.util.List |
systemCaCertificates()
Returns the system default CA certificate database for your system. |
boolean |
waitForEncrypted()
Waits until the socket has completed the SSL handshake and has emitted encrypted() , or msecs milliseconds, whichever comes first. |
boolean |
waitForEncrypted(int msecs)
Waits until the socket has completed the SSL handshake and has emitted encrypted() , or msecs milliseconds, whichever comes first. |
Methods inherited from class com.trolltech.qt.network.QAbstractSocket |
---|
abort, connectToHost, connectToHost, connectToHost, connectToHost, connectToHost, connectToHost, disconnectFromHost, disconnectFromHostImplementation, error, flush, isValid, localAddress, localPort, peerAddress, peerName, peerPort, proxy, readBufferSize, setLocalAddress, setLocalPort, setPeerAddress, setPeerName, setPeerPort, setProxy, setReadBufferSize, setSocketDescriptor, setSocketDescriptor, setSocketDescriptor, setSocketError, setSocketState, socketDescriptor, socketType, state, waitForConnected, waitForConnected, waitForDisconnected, waitForDisconnected |
Methods inherited from class com.trolltech.qt.core.QIODevice |
---|
atEnd, bytesAvailable, bytesToWrite, canReadLine, close, errorString, getByte, isOpen, isReadable, isSequential, isTextModeEnabled, isWritable, open, open, openMode, peek, peek, pos, putByte, read, read, readAll, readData, readLine, readLine, readLine, readLineData, reset, seek, setErrorString, setOpenMode, setOpenMode, setTextModeEnabled, size, ungetByte, waitForBytesWritten, waitForReadyRead, write, write, writeData |
Methods inherited from class com.trolltech.qt.core.QObject |
---|
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty |
Methods inherited from class com.trolltech.qt.QtJambiObject |
---|
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr |
Methods inherited from class com.trolltech.qt.QSignalEmitter |
---|
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread |
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal |
---|
__qt_signalInitialization |
Methods inherited from class java.lang.Object |
---|
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface com.trolltech.qt.QtJambiInterface |
---|
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership |
Field Detail |
---|
public final QSignalEmitter.Signal0 encrypted
QSslSocket::isEncrypted()
will return true, and all further transmissions on the socket will be encrypted. QSslSocket::connectToHostEncrypted()
, and QSslSocket::isEncrypted()
.
public final QSignalEmitter.Signal1 encryptedBytesWritten
This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <>:
This signal is emitted when QSslSocket enters encrypted mode. After this signal has been emitted, QSslSocket::isEncrypted()
will return true, and all further transmissions on the socket will be encrypted.
QSslSocket::connectToHostEncrypted()
, and QSslSocket::isEncrypted()
.
public final QSignalEmitter.Signal1 modeChanged
This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.network.QSslSocket$SslMode(named: mode)>:
This signal is emitted when QSslSocket changes from QSslSocket::UnencryptedMode
to either QSslSocket::SslClientMode
or QSslSocket::SslServerMode
. mode is the new mode.
QSslSocket::mode()
.
public final QSignalEmitter.Signal1 peerVerifyError
This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.network.QSslError(named: error)>:
QSslSocket can emit this signal several times during the SSL handshake, before encryption has been established, to indicate that an error has occurred while establishing the identity of the peer. The error is usually an indication that QSslSocket is unable to securely identify the peer.
This signal provides you with an early indication when something's wrong. By connecting to this signal, you can manually choose to tear down the connection from inside the connected slot before the handshake has completed. If no action is taken, QSslSocket will proceed to emitting QSslSocket::sslErrors()
.
sslErrors()
.
public final QSignalEmitter.Signal1 sslErrors
This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.util.List QSslSocket emits this signal after the SSL handshake to indicate that one or more errors have occurred while establishing the identity of the peer. The errors are usually an indication that QSslSocket is unable to securely identify the peer. Unless any action is taken, the connection will be dropped after this signal has been emitted. If you want to continue connecting despite the errors that have occurred, you must call errors contains one or more errors that prevent QSslSocket from verifying the identity of the peer. Note: You cannot use
QSslSocket::ignoreSslErrors()
from inside a slot connected to this signal. If you need to access the error list at a later point, you can call sslErrors()
(without arguments). Qt::QueuedConnection
when connecting to this signal, or calling QSslSocket::ignoreSslErrors()
will have no effect. peerVerifyError()
.
Constructor Detail |
---|
public QSslSocket()
QObject
's constructor. The new socket's cipher
suite is set to the one returned by the static method defaultCiphers()
.
public QSslSocket(QObject parent)
QObject
's constructor. The new socket's cipher
suite is set to the one returned by the static method defaultCiphers()
.
Method Detail |
---|
public final void addCaCertificate(QSslCertificate certificate)
To add multiple certificates, use addCaCertificates()
.
caCertificates()
, and setCaCertificates()
.
public final void addCaCertificates(java.util.List certificates)
For more precise control, use addCaCertificate()
.
caCertificates()
, and addDefaultCaCertificate()
.
public final boolean addCaCertificates(java.lang.String path, QSsl.EncodingFormat format)
The CA certificate database is used by the socket during the handshake phase to validate the peer's certificate.
For more precise control, use addCaCertificate()
.
addCaCertificate()
, and QSslCertificate::fromPath()
.
public final boolean addCaCertificates(java.lang.String path)
The CA certificate database is used by the socket during the handshake phase to validate the peer's certificate.
For more precise control, use addCaCertificate()
.
addCaCertificate()
, and QSslCertificate::fromPath()
.
public final boolean addCaCertificates(java.lang.String path, QSsl.EncodingFormat format, QRegExp.PatternSyntax syntax)
The CA certificate database is used by the socket during the handshake phase to validate the peer's certificate.
For more precise control, use addCaCertificate()
.
addCaCertificate()
, and QSslCertificate::fromPath()
.
public final java.util.List caCertificates()
addCaCertificate()
, addCaCertificates()
, and setCaCertificates()
. addCaCertificate()
, addCaCertificates()
, and setCaCertificates()
.
public final java.util.List ciphers()
By default, the handshake phase can choose any of the ciphers supported by this system's SSL libraries, which may vary from system to system. The list of ciphers supported by this system's SSL libraries is returned by supportedCiphers()
. You can restrict the list of ciphers used for choosing the session cipher for this socket by calling setCiphers()
with a subset of the supported ciphers. You can revert to using the entire set by calling setCiphers()
with the list returned by supportedCiphers()
.
You can restrict the list of ciphers used for choosing the session cipher for all sockets by calling setDefaultCiphers()
with a subset of the supported ciphers. You can revert to using the entire set by calling setCiphers()
with the list returned by supportedCiphers()
.
setCiphers()
, defaultCiphers()
, setDefaultCiphers()
, and supportedCiphers()
.
public final void connectToHostEncrypted(java.lang.String hostName, char port, QIODevice.OpenModeFlag[] mode)
public final void connectToHostEncrypted(java.lang.String hostName, char port)
public final void connectToHostEncrypted(java.lang.String hostName, char port, QIODevice.OpenMode mode)
public final long encryptedBytesAvailable()
public final long encryptedBytesToWrite()
public final void ignoreSslErrors()
sslErrors()
, or before the handshake phase. If you don't call this slot, either in response to errors or before the handshake, the connection will be dropped after the sslErrors()
signal has been emitted. If there are no errors during the SSL handshake phase (i.e., the identity of the peer is established with no problems), QSslSocket will not emit the sslErrors()
signal, and it is unnecessary to call this function.
Ignoring errors that occur during an SSL handshake should be done with caution. A fundamental characteristic of secure connections is that they should be established with an error free handshake.
sslErrors()
.
public final boolean isEncrypted()
An encrypted socket encrypts all data that is written by calling write()
or putChar() before the data is written to the network, and descrypts all incoming data as the data is received from the network, before you call read()
, readLine()
or getChar().
QSslSocket emits encrypted()
when it enters encrypted mode.
You can call sessionCipher()
to find which cryptographic cipher is used to encrypt and decrypt your data.
mode()
.
public final QSslCertificate localCertificate()
certificate
, or an empty certificate if no local certificate has been assigned. setLocalCertificate()
, and privateKey()
.
public final QSslSocket.SslMode mode()
UnencryptedMode
, where QSslSocket behaves identially to QTcpSocket
, or one of SslClientMode
or SslServerMode
, where the client is either negotiating or in encrypted mode. When the mode changes, QSslSocket emits modeChanged()
SslMode
.
public final QSslCertificate peerCertificate()
The peer certificate is checked automatically during the handshake phase, so this function is normally used to fetch the certificate for display or for connection diagnostic purposes. It contains information about the peer, including its host name, the certificate issuer, and the peer's public key.
Because the peer certificate is set during the handshake phase, it is safe to access the peer certificate from a slot connected to the sslErrors()
signal or the encrypted()
signal.
If a null certificate is returned, it can mean the SSL handshake failed, or it can mean the host you are connected to doesn't have a certificate, or it can mean there is no connection.
If you want to check the peer's complete chain of certificates, use peerCertificateChain()
to get them all at once.
peerCertificateChain()
.
public final java.util.List peerCertificateChain()
Peer certificates are checked automatically during the handshake phase. This function is normally used to fetch certificates for display, or for performing connection diagnostics. Certificates contain information about the peer and the certificate issuers, including host name, issuer names, and issuer public keys.
The peer certificates are set in QSslSocket during the handshake phase, so it is safe to call this function from a slot connected to the sslErrors()
signal or the encrypted()
signal.
If an empty list is returned, it can mean the SSL handshake failed, or it can mean the host you are connected to doesn't have a certificate, or it can mean there is no connection.
If you want to get only the peer's immediate certificate, use peerCertificate()
.
peerCertificate()
.
public final int peerVerifyDepth()
The certificates are checked in issuing order, starting with the peer's own certificate, then its issuer's certificate, and so on.
setPeerVerifyDepth()
, and peerVerifyMode()
.
public final QSslSocket.PeerVerifyMode peerVerifyMode()
The default mode is AutoVerifyPeer
, which tells QSslSocket to use VerifyPeer
for clients, QueryPeer
for clients.
setPeerVerifyMode()
, peerVerifyDepth()
, and mode()
.
public final QSslKey privateKey()
setPrivateKey()
, and localCertificate()
.
public final QSsl.SslProtocol protocol()
QSsl::SslV3
is used. setProtocol()
.
public final QSslCipher sessionCipher()
cipher
, or a null cipher if the connection isn't encrypted. The socket's cipher for the session is set during the handshake phase. The cipher is used to encrypt and decrypt data transmitted through the socket. QSslSocket also provides functions for setting the ordered list of ciphers from which the handshake phase will eventually select the session cipher. This ordered list must be in place before the handshake phase begins.
ciphers()
, setCiphers()
, setDefaultCiphers()
, defaultCiphers()
, and supportedCiphers()
.
public final void setCaCertificates(java.util.List certificates)
The CA certificate database can be reset to the current default CA certificate database by calling this function with the list of CA certificates returned by defaultCaCertificates()
.
caCertificates()
, and defaultCaCertificates()
.
public final void setCiphers(java.util.List ciphers)
supportedCiphers()
. Restricting the cipher suite must be done before the handshake phase, where the session cipher is chosen.
ciphers()
, setDefaultCiphers()
, and supportedCiphers()
.
public final void setCiphers(java.lang.String ciphers)
QSslSocket socket; socket.setCiphers("DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA");Each cipher name in ciphers must be the name of a cipher in the list returned by
supportedCiphers()
. Restricting the cipher suite must be done before the handshake phase, where the session cipher is chosen. ciphers()
, setDefaultCiphers()
, and supportedCiphers()
.
public final void setLocalCertificate(QSslCertificate certificate)
The local certificate and private key are always necessary for server sockets, but are also rarely used by client sockets if the server requires the client to authenticate.
localCertificate()
, and setPrivateKey()
.
public final void setLocalCertificate(java.lang.String fileName)
Sets the socket's local certificate
to the first one found in file path, which is parsed according to the specified format.
public final void setLocalCertificate(java.lang.String fileName, QSsl.EncodingFormat format)
Sets the socket's local certificate
to the first one found in file path, which is parsed according to the specified format.
public final void setPeerVerifyDepth(int depth)
The certificates are checked in issuing order, starting with the peer's own certificate, then its issuer's certificate, and so on.
peerVerifyDepth()
, and setPeerVerifyMode()
.
public final void setPeerVerifyMode(QSslSocket.PeerVerifyMode mode)
The default mode is AutoVerifyPeer
, which tells QSslSocket to use VerifyPeer
for clients, QueryPeer
for clients.
Setting this mode after encryption has started has no effect on the current connection.
peerVerifyMode()
, setPeerVerifyDepth()
, and mode()
.
public final void setPrivateKey(QSslKey key)
key
to key. The private key and the local certificate
are used by clients and servers that must prove their identity to SSL peers. Both the key and the local certificate are required if you are creating an SSL server socket. If you are creating an SSL client socket, the key and local certificate are required if your client must identify itself to an SSL server.
privateKey()
, and setLocalCertificate()
.
public final void setPrivateKey(java.lang.String fileName, QSsl.KeyAlgorithm algorithm, QSsl.EncodingFormat format)
Reads the string in file fileName and decodes it using a specified algorithm and encoding format to construct an SSL key
. If the encoded key is encrypted, passPhrase is used to decrypt it.
The socket's private key is set to the constructed key. The private key and the local certificate
are used by clients and servers that must prove their identity to SSL peers.
Both the key and the local certificate are required if you are creating an SSL server socket. If you are creating an SSL client socket, the key and local certificate are required if your client must identify itself to an SSL server.
privateKey()
, and setLocalCertificate()
.
public final void setPrivateKey(java.lang.String fileName, QSsl.KeyAlgorithm algorithm)
Reads the string in file fileName and decodes it using a specified algorithm and encoding format to construct an SSL key
. If the encoded key is encrypted, passPhrase is used to decrypt it.
The socket's private key is set to the constructed key. The private key and the local certificate
are used by clients and servers that must prove their identity to SSL peers.
Both the key and the local certificate are required if you are creating an SSL server socket. If you are creating an SSL client socket, the key and local certificate are required if your client must identify itself to an SSL server.
privateKey()
, and setLocalCertificate()
.
public final void setPrivateKey(java.lang.String fileName)
Reads the string in file fileName and decodes it using a specified algorithm and encoding format to construct an SSL key
. If the encoded key is encrypted, passPhrase is used to decrypt it.
The socket's private key is set to the constructed key. The private key and the local certificate
are used by clients and servers that must prove their identity to SSL peers.
Both the key and the local certificate are required if you are creating an SSL server socket. If you are creating an SSL client socket, the key and local certificate are required if your client must identify itself to an SSL server.
privateKey()
, and setLocalCertificate()
.
public final void setPrivateKey(java.lang.String fileName, QSsl.KeyAlgorithm algorithm, QSsl.EncodingFormat format, QByteArray passPhrase)
Reads the string in file fileName and decodes it using a specified algorithm and encoding format to construct an SSL key
. If the encoded key is encrypted, passPhrase is used to decrypt it.
The socket's private key is set to the constructed key. The private key and the local certificate
are used by clients and servers that must prove their identity to SSL peers.
Both the key and the local certificate are required if you are creating an SSL server socket. If you are creating an SSL client socket, the key and local certificate are required if your client must identify itself to an SSL server.
privateKey()
, and setLocalCertificate()
.
public final void setProtocol(QSsl.SslProtocol protocol)
protocol()
.
public final boolean setSocketDescriptor(int socketDescriptor, QAbstractSocket.SocketState state, QIODevice.OpenMode openMode)
Note: It is not possible to initialize two sockets with the same native socket descriptor.
socketDescriptor()
.
setSocketDescriptor
in class QAbstractSocket
public final void setSslConfiguration(QSslConfiguration config)
It is not possible to set the SSL-state related fields.
sslConfiguration()
, setLocalCertificate()
, setPrivateKey()
, setCaCertificates()
, and setCiphers()
.
public final QSslConfiguration sslConfiguration()
The SSL configuration also contains fields that can change with time without notice.
setSslConfiguration()
, localCertificate()
, peerCertificate()
, peerCertificateChain()
, sessionCipher()
, privateKey()
, ciphers()
, and caCertificates()
.
public final java.util.List sslErrors()
sslErrors()
signal. If the connection has been encrypted with no errors, this function will return an empty list. connectToHostEncrypted()
.
public final void startClientEncryption()
ConnectedState
but still in the UnencryptedMode
. If it is not yet connected, or if it is already encrypted, this function has no effect. Clients that implement STARTTLS functionality often make use of delayed SSL handshakes. Most other clients can avoid calling this function directly by using connectToHostEncrypted()
instead, which automatically performs the handshake.
connectToHostEncrypted()
, and startServerEncryption()
.
public final void startServerEncryption()
ConnectedState
but still in UnencryptedMode
. If it is not connected or it is already encrypted, the function has no effect. For server sockets, calling this function is the only way to initiate the SSL handshake. Most servers will call this function immediately upon receiving a connection, or as a result of having received a protocol-specific command to enter SSL mode (e.g, the server may respond to receiving the string "STARTTLS\r\n" by calling this function).
The most common way to implement an SSL server is to create a subclass of QTcpServer
and reimplement QTcpServer::incomingConnection()
. The returned socket descriptor is then passed to QSslSocket::setSocketDescriptor()
.
connectToHostEncrypted()
, and startClientEncryption()
.
public final boolean waitForEncrypted()
encrypted()
, or msecs milliseconds, whichever comes first. If encrypted()
has been emitted, this function returns true; otherwise (e.g., the socket is disconnected, or the SSL handshake fails), false is returned. The following example waits up to one second for the socket to be encrypted:
The following code example is written in c++.
socket->connectToHostEncrypted("imap", 993); if (socket->waitForEncrypted(1000)) qDebug("Encrypted!");If msecs is -1, this function will not time out.
startClientEncryption()
, startServerEncryption()
, encrypted()
, and isEncrypted()
.
public final boolean waitForEncrypted(int msecs)
encrypted()
, or msecs milliseconds, whichever comes first. If encrypted()
has been emitted, this function returns true; otherwise (e.g., the socket is disconnected, or the SSL handshake fails), false is returned. The following example waits up to one second for the socket to be encrypted:
The following code example is written in c++.
socket->connectToHostEncrypted("imap", 993); if (socket->waitForEncrypted(1000)) qDebug("Encrypted!");If msecs is -1, this function will not time out.
startClientEncryption()
, startServerEncryption()
, encrypted()
, and isEncrypted()
.
public static void addDefaultCaCertificate(QSslCertificate certificate)
defaultCaCertificates()
, and addCaCertificates()
.
public static void addDefaultCaCertificates(java.util.List certificates)
defaultCaCertificates()
, and addCaCertificates()
.
public static boolean addDefaultCaCertificates(java.lang.String path, QSsl.EncodingFormat format)
Each SSL socket's CA certificate database is initialized to the default CA certificate database.
defaultCaCertificates()
, addCaCertificates()
, and addDefaultCaCertificate()
.
public static boolean addDefaultCaCertificates(java.lang.String path)
Each SSL socket's CA certificate database is initialized to the default CA certificate database.
defaultCaCertificates()
, addCaCertificates()
, and addDefaultCaCertificate()
.
public static boolean addDefaultCaCertificates(java.lang.String path, QSsl.EncodingFormat format, QRegExp.PatternSyntax syntax)
Each SSL socket's CA certificate database is initialized to the default CA certificate database.
defaultCaCertificates()
, addCaCertificates()
, and addDefaultCaCertificate()
.
public static java.util.List defaultCaCertificates()
setDefaultCaCertificates()
. Each SSL socket's CA certificate database is initialized to the default CA certificate database.
setDefaultCaCertificates()
, and caCertificates()
.
public static java.util.List defaultCiphers()
By default, the handshake phase can choose any of the ciphers supported by this system's SSL libraries, which may vary from system to system. The list of ciphers supported by this system's SSL libraries is returned by supportedCiphers()
.
setDefaultCiphers()
, and supportedCiphers()
.
public static void setDefaultCaCertificates(java.util.List certificates)
Each SSL socket's CA certificate database is initialized to the default CA certificate database.
defaultCaCertificates()
, and addDefaultCaCertificate()
.
public static void setDefaultCiphers(java.util.List ciphers)
supportedCiphers()
. Restricting the default cipher suite only affects SSL sockets that perform their handshake phase after the default cipher suite has been changed.
setCiphers()
, defaultCiphers()
, and supportedCiphers()
.
public static java.util.List supportedCiphers()
defaultCiphers()
, ciphers()
, and setCiphers()
.
public static boolean supportsSsl()
public static java.util.List systemCaCertificates()
defaultCaCertificates()
. You can replace that database with your own with setDefaultCaCertificates()
. caCertificates()
, defaultCaCertificates()
, and setDefaultCaCertificates()
.
protected void connectToHostImplementation(java.lang.String host, int port, QIODevice.OpenMode mode)
QAbstractSocket
connectToHostImplementation
in class QAbstractSocket
protected void connectToHostImplementation(java.lang.String host, int port, QIODevice.OpenModeFlag[] mode)
QAbstractSocket
connectToHostImplementation
in class QAbstractSocket
protected void connectToHostImplementation(java.lang.String host, int port)
QAbstractSocket
connectToHostImplementation
in class QAbstractSocket
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |