QDtls Class

Dokumentation der Mitgliedsfunktionen

[explicit] QDtls::QDtls(QSslSocket::SslMode mode, QObject *parent = nullptr)

Erzeugt ein QDtls-Objekt, parent wird an den QObject -Konstruktor übergeben. mode ist QSslSocket::SslServerMode für eine serverseitige DTLS-Verbindung oder QSslSocket::SslClientMode für einen Client.

Siehe auch sslMode() und QSslSocket::SslMode.

[virtual noexcept] QDtls::~QDtls()

Zerstört das Objekt QDtls.

bool QDtls::abortHandshake(QUdpSocket *socket)

Bricht den laufenden Handshake ab. Gibt true zurück, wenn unter socket ein Handshake im Gange war; andernfalls wird ein entsprechender Fehler gesetzt und false zurückgegeben.

Siehe auch doHandshake() und resumeHandshake().

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

Gibt den aktuellen Hash-Algorithmus und das Geheimnis zurück, entweder die Standardwerte oder die zuvor durch einen Aufruf von setCookieGeneratorParameters() gesetzten.

Der Standard-Hash-Algorithmus ist QCryptographicHash::Sha256, wenn Qt so konfiguriert wurde, dass es ihn unterstützt, andernfalls QCryptographicHash::Sha1. Das Standardgeheimnis wird aus dem Backend-spezifischen kryptographisch starken Pseudozufallszahlengenerator gewonnen.

Siehe auch setCookieGeneratorParameters(), QDtlsClientVerifier, und cookieGeneratorParameters().

QByteArray QDtls::decryptDatagram(QUdpSocket *socket, const QByteArray &dgram)

Entschlüsselt dgram und gibt seinen Inhalt als Klartext zurück. Der Handshake muss abgeschlossen sein, bevor die Datagramme entschlüsselt werden können. Je nach Typ der TLS-Nachricht kann die Verbindung in socket schreiben, das ein gültiger Zeiger sein muss.

bool QDtls::doHandshake(QUdpSocket *socket, const QByteArray &dgram = {})

Startet oder setzt einen DTLS-Handshake fort. socket muss ein gültiger Zeiger sein. Wenn ein serverseitiger DTLS-Handshake gestartet wird, muss dgram die anfängliche ClientHello-Nachricht enthalten, die aus QUdpSocket gelesen wurde. Diese Funktion gibt true zurück, wenn kein Fehler gefunden wurde. Der Handshake-Status kann mit handshakeState() getestet werden. false bedeutet, dass ein Fehler aufgetreten ist; verwenden Sie dtlsError() für weitere Informationen.

if (!dtls.doHandshake(&socket, dgram)) {
    if (dtls.dtlsError() == QDtlsError::PeerVerificationError)
        dtls.abortAfterError(&socket);
}

Siehe auch handshakeState(), dtlsError(), ignoreVerificationErrors(), resumeHandshake(), und abortHandshake().

QSslConfiguration QDtls::dtlsConfiguration() const

Gibt entweder die Standard-DTLS-Konfiguration oder die durch einen früheren Aufruf von setDtlsConfiguration() gesetzte Konfiguration zurück.

Siehe auch setDtlsConfiguration() und QSslConfiguration::defaultDtlsConfiguration().

QDtlsError QDtls::dtlsError() const

Gibt den letzten Fehler zurück, der bei der Verbindung oder bei QDtlsError::NoError aufgetreten ist.

Siehe auch dtlsErrorString() und QDtlsError.

QString QDtls::dtlsErrorString() const

Liefert eine textuelle Beschreibung des letzten Fehlers, der bei der Verbindung aufgetreten ist, oder einen leeren String.

Siehe auch dtlsError().

bool QDtls::handleTimeout(QUdpSocket *socket)

Tritt während des Handshakes eine Zeitüberschreitung auf, wird das Signal handshakeTimeout() ausgegeben. Die Anwendung muss handleTimeout() aufrufen, um Handshake-Nachrichten erneut zu übermitteln; handleTimeout() gibt true zurück, wenn eine Zeitüberschreitung aufgetreten ist, andernfalls false. socket muss ein gültiger Zeiger sein.

Siehe auch handshakeTimeout().

QDtls::HandshakeState QDtls::handshakeState() const

Gibt den aktuellen Handshake-Status für diese QDtls zurück.

Siehe auch doHandshake() und QDtls::HandshakeState.

[signal] void QDtls::handshakeTimeout()

Paketverluste können zu Zeitüberschreitungen während der Handshake-Phase führen. In diesem Fall sendet QDtls ein handshakeTimeout()-Signal. Rufen Sie handleTimeout() auf, um die Handshake-Nachrichten erneut zu übermitteln:

DtlsClient::DtlsClient()
{
    // Some initialization code here ...
    connect(&clientDtls, &QDtls::handshakeTimeout, this, &DtlsClient::handleTimeout);
}

void DtlsClient::handleTimeout()
{
    clientDtls.handleTimeout(&clientSocket);
}

Siehe auch handleTimeout().

void QDtls::ignoreVerificationErrors(const QList<QSslError> &errorsToIgnore)

Mit dieser Methode wird QDtls angewiesen, nur die in errorsToIgnore angegebenen Fehler zu ignorieren.

Wenn Sie zum Beispiel eine Verbindung zu einem Server herstellen wollen, der ein selbstsigniertes Zertifikat verwendet, können Sie den folgenden Ausschnitt verwenden:

QList<QSslCertificate> cert = QSslCertificate::fromPath("server-certificate.pem"_L1);
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QDtls dtls;
dtls.ignoreVerificationErrors(expectedSslErrors);
dtls.doHandshake(udpSocket);

Sie können diese Funktion auch aufrufen, nachdem doHandshake() auf den Fehler QDtlsError::PeerVerificationError gestoßen ist, und dann den Handshake durch Aufruf von resumeHandshake() fortsetzen.

Spätere Aufrufe dieser Funktion ersetzen die Liste der Fehler, die in früheren Aufrufen übergeben wurden. Sie können die Liste der Fehler, die Sie ignorieren wollen, löschen, indem Sie diese Funktion mit einer leeren Liste aufrufen.

Siehe auch doHandshake(), resumeHandshake(), und QSslError.

bool QDtls::isConnectionEncrypted() const

Gibt true zurück, wenn der DTLS-Handshake erfolgreich abgeschlossen wurde.

Siehe auch doHandshake() und handshakeState().

quint16 QDtls::mtuHint() const

Gibt den Wert zurück, der zuvor durch setMtuHint() gesetzt wurde. Der Standardwert ist 0.

Siehe auch setMtuHint().

QHostAddress QDtls::peerAddress() const

Gibt die Adresse der Gegenstelle zurück, die mit setPeer() oder QHostAddress::Null festgelegt wurde.

Siehe auch setPeer().

quint16 QDtls::peerPort() const

Gibt die Portnummer der Gegenstelle zurück, die mit setPeer() festgelegt wurde, oder 0.

Siehe auch setPeer().

QList<QSslError> QDtls::peerVerificationErrors() const

Gibt Fehler zurück, die bei der Feststellung der Identität der Gegenstelle gefunden wurden.

Wenn Sie die Verbindung trotz der aufgetretenen Fehler fortsetzen wollen, müssen Sie ignoreVerificationErrors() aufrufen.

QString QDtls::peerVerificationName() const

Gibt den durch setPeer() oder setPeerVerificationName() festgelegten Hostnamen zurück. Der Standardwert ist eine leere Zeichenkette.

Siehe auch setPeerVerificationName() und setPeer().

[signal] void QDtls::pskRequired(QSslPreSharedKeyAuthenticator *authenticator)

QDtls sendet dieses Signal, wenn er eine PSK-Ciphersuite aushandelt, so dass eine PSK-Authentifizierung erforderlich ist.

Bei der Verwendung von PSK muss der Client dem Server eine gültige Identität und einen gültigen Pre-Shared Key senden, damit der TLS-Handshake fortgesetzt werden kann. Anwendungen können diese Informationen in einem mit diesem Signal verbundenen Slot bereitstellen, indem sie das übergebene authenticator Objekt entsprechend ihren Bedürfnissen ausfüllen.

Siehe auch QSslPreSharedKeyAuthenticator.

bool QDtls::resumeHandshake(QUdpSocket *socket)

Wenn Peer-Verifizierungsfehler während des Handshake ignoriert wurden, nimmt resumeHandshake() den Handshake wieder auf und schließt ihn ab und gibt true zurück. socket muss ein gültiger Zeiger sein. Gibt false zurück, wenn der Handshake nicht fortgesetzt werden konnte.

Siehe auch doHandshake(), abortHandshake(), peerVerificationErrors(), und ignoreVerificationErrors().

QSslCipher QDtls::sessionCipher() const

Gibt die kryptographische cipher zurück, die von dieser Verbindung verwendet wird, oder eine Null-Chiffre, wenn die Verbindung nicht verschlüsselt ist. Die Chiffre für die Sitzung wird während der Handshake-Phase ausgewählt. Die Chiffre wird zum Verschlüsseln und Entschlüsseln von Daten verwendet.

QSslConfiguration bietet Funktionen zum Festlegen der geordneten Liste von Chiffren, aus der die Handshake-Phase schließlich die Sitzungs-Chiffre auswählt. Diese geordnete Liste muss vorhanden sein, bevor die Handshake-Phase beginnt.

Siehe auch QSslConfiguration, setDtlsConfiguration(), und dtlsConfiguration().

QSsl::SslProtocol QDtls::sessionProtocol() const

Gibt die von dieser Verbindung verwendete DTLS-Protokollversion zurück, oder UnknownProtocol, wenn die Verbindung noch nicht verschlüsselt ist. Das Protokoll für die Verbindung wird während der Handshake-Phase ausgewählt.

setDtlsConfiguration() kann die bevorzugte Version festlegen, bevor der Handshake beginnt.

Siehe auch setDtlsConfiguration(), QSslConfiguration, QSslConfiguration::defaultDtlsConfiguration(), und QSslConfiguration::setProtocol().

bool QDtls::setCookieGeneratorParameters(const QDtls::GeneratorParameters &params)

Setzt den kryptographischen Hash-Algorithmus und das Geheimnis von params. Diese Funktion wird nur für eine serverseitige QDtls Verbindung benötigt. Gibt bei Erfolg true zurück.

Siehe auch cookieGeneratorParameters(), doHandshake(), QDtlsClientVerifier, und QDtlsClientVerifier::cookieGeneratorParameters().

bool QDtls::setDtlsConfiguration(const QSslConfiguration &configuration)

Setzt die TLS-Konfiguration der Verbindung von configuration und gibt bei Erfolg true zurück.

Siehe auch dtlsConfiguration() und doHandshake().

void QDtls::setMtuHint(quint16 mtuHint)

mtuHint ist die maximale Übertragungseinheit (MTU), die entweder ermittelt oder von der Anwendung geschätzt wurde. Es ist nicht erforderlich, dass die Anwendung diesen Wert festlegt.

Siehe auch mtuHint() und QAbstractSocket::PathMtuSocketOption.

bool QDtls::setPeer(const QHostAddress &address, quint16 port, const QString &verificationName = {})

Legt die Adresse der Gegenstelle, port, und den Hostnamen fest und gibt bei Erfolg true zurück. address darf nicht null, multicast oder broadcast sein. verificationName ist der Hostname, der für die Zertifikatsüberprüfung verwendet wird.

Siehe auch peerAddress(), peerPort(), und peerVerificationName().

bool QDtls::setPeerVerificationName(const QString &name)

Legt den Host name fest, der für die Zertifikatsüberprüfung verwendet wird, und gibt bei Erfolg true zurück.

Siehe auch peerVerificationName() und setPeer().

bool QDtls::shutdown(QUdpSocket *socket)

Sendet eine verschlüsselte Shutdown-Warnmeldung und schließt die DTLS-Verbindung. Der Handshake-Status wechselt zu QDtls::HandshakeNotStarted. socket muss ein gültiger Zeiger sein. Diese Funktion gibt bei Erfolg true zurück.

Siehe auch doHandshake().

QSslSocket::SslMode QDtls::sslMode() const

Gibt QSslSocket::SslServerMode für eine serverseitige Verbindung und QSslSocket::SslClientMode für einen Client zurück.

Siehe auch QDtls() und QSslSocket::SslMode.

qint64 QDtls::writeDatagramEncrypted(QUdpSocket *socket, const QByteArray &dgram)

Verschlüsselt dgram und schreibt die verschlüsselten Daten in socket. Gibt die Anzahl der geschriebenen Bytes zurück oder -1 im Falle eines Fehlers. Der Handshake muss abgeschlossen sein, bevor verschlüsselte Daten geschrieben werden. socket muss ein gültiger Zeiger sein.

Siehe auch doHandshake(), handshakeState(), isConnectionEncrypted(), und dtlsError().